home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir41 / x10xa200.zip / XA_200.TXT < prev    next >
Text File  |  1993-10-16  |  127KB  |  3,346 lines
  1. XA
  2. X10 Command Interpreter
  3. Version 2.00 - October 1993
  4. Copyright 1993 by Bruce Christensen. All Rights Reserved.
  5.  
  6.  
  7. ═════════════════════════════════════════════════════════════════════
  8. 1.   Shareware
  9. ═════════════════════════════════════════════════════════════════════
  10.  
  11. This floppy contains a set of useful DOS utilities for X10's CP-290
  12. Computer Interface.  These programs are being marketed using the
  13. SHAREWARE concept which allows you a complete evaluation of the
  14. product before you are required to register. Shareware provides you
  15. with low-cost, high-performance software and support.  Shareware also
  16. provides incentives for programmers to continue to develop new
  17. products.  If you find XA and its support files useful and you
  18. continue to use them after a trial period not to exceed 45 days, you
  19. must make a registration payment of $29 to the author.  When you
  20. register, you will receive the latest, full-featured version of XA
  21. along with a printed User's Manual.  For more information, see
  22. "License Agreement and Registration" and register your copy of XA.
  23.  
  24. ═════════════════════════════════════════════════════════════════════
  25. 2.   Introduction 
  26. ═════════════════════════════════════════════════════════════════════
  27.  
  28. You are probably familiar with the menu-driven program (X10.EXE)
  29. supplied with your CP-290.  The software approach used in that
  30. implementation is great for beginners since it offers a fool-proof
  31. method of organizing commands and events. Unfortunately, that method
  32. also becomes a bottle-neck every time you want to activate a single
  33. module via your computer.  It gets even worse when trying to maintain
  34. a schedule of lighting events that vary due to seasonal changes.  XA
  35. is a shareware package designed to alleviate many of the frustrations
  36. you may have experienced with the X10-supplied software.  In
  37. addition, XA makes schedule maintenance a breeze.  Soon, your
  38. computer will automatically handle the monotony of CP-290 scheduling
  39. for you. Be sure to read this manual to take full advantage of XA's
  40. power.
  41.  
  42.  
  43. What is XA?
  44. ─────────────────────────────────────────────────────────────────────
  45.  
  46. The XA program is an interpreter.  XA translates English-like
  47. sentences into commands that are understood by the CP-290.  For
  48. instance, you can quickly tell XA to turn on a set of lights with
  49. the following DOS command:
  50.  
  51.      XA "PORCH ON"
  52.  
  53. XA knows that the PORCH lights are addressed at HOUSE A UNIT 9, or
  54. whatever address you choose (you define modules and their addresses
  55. in the file XA.INI, discussed later).  Since XA accepts commands
  56. from  the DOS prompt, you can place statements like these in your
  57. batch files too.  For instance, I use an X10-controlled nightlight
  58. near our downstairs phone to warn other family members if I'm
  59. "on-line" with a remote computer or BBS.  The light is turned on
  60. prior to the session, and turned off when I'm finished.  Here's the
  61. sample PHONE.BAT with  X10 commands:
  62.  
  63.      XA "WARNING_LAMP ON"        
  64.      TELIX (or ProComm) statements here        
  65.      XA "WARNING_LAMP OFF"
  66.      
  67. XA will also process X10 commands and events contained in a file. 
  68. This is ideal for maintaining the CP-290's event schedule, or for
  69. running a Christmas "lightshow".  Simply tell XA which file to read,
  70. and XA does all the work.  For instance, to download my event
  71. schedule to the CP-290, type:
  72.  
  73.      XA f=XA.CMD
  74.  
  75. XA calculates sunrise and sunset times based on your latitude and 
  76. longitude, and automatically compensates for any Daylight Savings
  77. changes.  XA can be programmed to handle events for special dates
  78. that may be weeks, months, or years in the future.  Best of all, XA
  79. can automatically update the CP-290 on a once-per-week basis without
  80. any intervention on your part (an Appliance module is needed to
  81. control your PC).
  82.  
  83.  
  84. Registered vs. Shareware
  85. ─────────────────────────────────────────────────────────────────────
  86.  
  87. The next section highlights the many additions to XA Version 2.00. 
  88. Note that some items are reserved only for "registered" users.  The
  89. "shareware" version of XA provides all the features of past versions,
  90. plus many newer features.  When you register your copy of XA, you
  91. will receive a floppy with a "registered" status allowing full use of
  92. the commands described in this manual. 
  93.  
  94. ═════════════════════════════════════════════════════════════════════
  95. 3.   Summary of NEW Features for Version 2.00 
  96. ═════════════════════════════════════════════════════════════════════
  97.  
  98. The last "official" release of XA was Version 1.07b (dated July,
  99. 1992).  Version 2.00 is a complete re-write, allowing such features
  100. as conditional statements, operators, and user-variables to be
  101. supported.  Also, XA performs sun-related calculations much faster. 
  102. The following list highlights the major enhancements of Version
  103. 2.00.  Additional details may be found in later sections.
  104.  
  105. * Improved HELP screens
  106.   Type "XA /?" at the DOS prompt to get on-line information about
  107.   XA's syntax and features.
  108.  
  109. * Power-fail recovery mode.
  110.   This feature allows you to restore the programmed state of each
  111.   module in the eventuality of a power failure, or other
  112.   circumstance.  XA determines the latest state of the module by
  113.   examining the CP-290's event schedule.  Selected modules may be
  114.   excluded from recovery, others can be forced to a particular
  115.   state no matter what XA determines. 
  116.  
  117. * Improved DATE handling.
  118.   A new token "EXCEPT" has been added which allows to program
  119.   events to occur EXCEPT when certain dates arrive:  
  120.  
  121.      DEFINE MEMORIAL_DAY DATE 5/31
  122.      BEDROOM_LIGHTS ON WEEKDAYS 6:30 EXCEPT MEMORIAL_DAY
  123.  
  124. * Automatic Daylight Savings Time adjustment.
  125.   Use the token DST to have XA determine when changes for Daylight
  126.   Savings or Standard Time should go into effect. This means you only
  127.   have to specify a single timezone token in your initialization file
  128.   (XA.INI). 
  129.  
  130. * IF/ELSE/ENDIF constructs.              (Registered Version Only)
  131.   Finally! Support for conditional statements within your command
  132.   files.  Now you can perform a test to see whether SUNRISE  falls
  133.   within a certain time period, and schedule events based on the 
  134.   result.  IF/ELSE statements may be nested up to 100 levels deep.
  135.  
  136. * Variable assignments                   (Registered Version Only)
  137.   Variables may be used as temporary storage locations.  These
  138.   variables may then be evaluated later using IF/ELSE constructs to
  139.   trigger a DIRECT command or to program an EVENT.
  140.  
  141. * Logical, Arithmetic operators.         (Registered Version Only)
  142.   Operations may be performed on variables and later evaluated.
  143.  
  144. * Appends new events automatically.
  145.   You may now easily append a new event from the command line
  146.   without having to figure out where the next "free" event resides
  147.   in the CP-290.  XA finds the empty event slot for you.
  148.  
  149. * GOSUB/RETURN
  150.   In addition to GOTO statements, XA now supports calling
  151.   subroutines (GOSUB), and returning to the original calling
  152.   statement (RETURN). 
  153.  
  154. * INPUT/OUTPUT (I/O) control.            (Registered Version Only)
  155.   Use your Joystick port, LPT port (or any other port) as a
  156.   general purpose Input/Output port. Connect switches and/or
  157.   relays to these ports and program XA to react to real-world
  158.   events.
  159.  
  160. * INCLUDE files
  161.   Use the INCLUDE token to instruct the XA parser to read
  162.   additional initialization or command files. Different files may
  163.   be included based on the results of conditional IF/ELSE
  164.   statements.
  165.  
  166. * Nested DEFINE support.
  167.   In the past, XA could not handle a statement with multiple
  168.   DEFINE substitutions.  The following is now permitted:
  169.  
  170.      DEFINE PORCH A1
  171.      DEFINE GARAGE A2
  172.      DEFINE OUTSIDE PORCH GARAGE
  173.  
  174. * "ALL_LIGHTS_ON", "ALL_UNITS_OFF".
  175.   These "undocumented" CP-290 commands are fully supported.
  176.  
  177. * Faster execution.
  178.   XA reduces the number of passes required to process a file. 
  179.   Sunrise/set calculations are faster. Also, a new token "FAST"
  180.   can be included in a direct command which informs XA to ignore
  181.   the CP-290 acknowledgement message thus speeding up overall
  182.   execution time.
  183.  
  184. * Conditional COLOR highlighting.          (Registered Version Only)
  185.   XA can optionally display each line of the XA.INI and command
  186.   file as it's parsed. In addition, you can define your own color
  187.   attributes for conditional statements that evaluate TRUE or
  188.   FALSE, as well as define special color attributes for EVENTS and
  189.   DIRECT commands.
  190.  
  191. * Shell to DOS capability.
  192.   XA can invoke a copy of COMMAND.COM allowing you to execute a
  193.   DOS program, batch file, etc. from within a command file. 
  194.   
  195. * Utility to locate CP-290 port connection.
  196.   A new utility called FINDX10.EXE searches all 4 COM ports for
  197.   the CP-290 interface.  If it is found, you are asked whether you
  198.   would like the parameters stored in the XA.INI file for you.  
  199.  
  200. * Expanded POWERUP.EXE Utility
  201.   An additional "week" argument has been added allowing you to
  202.   detect certain conditions. For example, on the 2nd Friday of the
  203.   month,  update the CP-290 and backup all hard drives.
  204.  
  205. Other Features 
  206. ─────────────────────────────────────────────────────────────────────
  207.  
  208. - SUNRISE-SUNSET calculations
  209.   XA calculates precise sunrise/sunset times for your location
  210.   based on the latitude and longitude of your city.  
  211.  
  212. - Specific DATE handling 
  213.   Request any event to occur days, months, even years from now. XA
  214.   expands X10's time base by allowing you to program an event for
  215.   any day in the future, or you can schedule an event to occur
  216.   between two defined dates. You can also program modules to NOT
  217.   activate on certain dates.   
  218.  
  219. - Time synchronization
  220.   XA can keep the internal clocks of your PC and CP-290 accurate
  221.   to within 1 second of each other.  You can set either clock
  222.   based on the time maintained by the other clock.  
  223.  
  224. Miscellaneous Features
  225. ─────────────────────────────────────────────────────────────────────
  226.  
  227. - You can program the CP-290 to repeat a series of commands to 
  228.   produce unique lighting effects.  
  229.  
  230. - X10.EXE compatible - creates X10.DAT file with the same module
  231.   names and events that were downloaded by XA. 
  232.  
  233. - Initialization file - XA.INI contains all module definitions,
  234.   communication parameters, location coordinates, and other
  235.   information that will greatly reduce redundant data used in
  236.   command files. 
  237.  
  238. - The tokens "TIMER", and "PAUSE" let you trigger X10 commands
  239.   after a number of seconds have elapsed, useful for synchronizing
  240.   X10-controlled lights with pre-recorded music.  "NOW" allows you
  241.   to program an event relative to the current time (for instance,
  242.   turn off a battery charger 14 hours from now).  "RANDOM"
  243.   provides an even better security mode by offering precise
  244.   control of random event times.
  245.  
  246. - Better reporting facilities.  XA has 2 report formats to
  247.   document the events you downloaded to the CP-290.
  248.  
  249. - Monitor events as the CP-290 executes them and optionally log
  250.   them to a file.
  251.  
  252. - The ability to change the base housecode without losing all the
  253.   data already stored in the interface.
  254.  
  255. - String substitution in the command file allows you to equate a
  256.   device (FAMILY_ROOM_LAMP) with its module address (A3).
  257.  
  258. - Comments are allowed in the file to properly document its
  259.   content.
  260.  
  261. ═════════════════════════════════════════════════════════════════════
  262. 4.   Utilities supplied with XA
  263. ═════════════════════════════════════════════════════════════════════
  264.  
  265. POWERUP.EXE
  266. ─────────────────────────────────────────────────────────────────────
  267.  
  268. This utility is provided for those of you who control your
  269. computer with an X10 Appliance module.  Powerup is designed to
  270. be called from your AUTOEXEC.BAT file.  You pass arguments to
  271. Powerup that specify a "window" of time based on day, week, and
  272. time. If your computer begins its boot phase during this window,
  273. it returns an errorlevel of 1, otherwise it returns a 0. This
  274. errorlevel can then be evaluated by simple batch file statements
  275. and a number of special functions can be executed.  For
  276. instance, you can have X10 turn on your computer at 3:00 AM
  277. every Sunday morning and automatically update the CP-290 with an
  278. entirely new schedule of events.  Your computer can then perform
  279. disk optimizations, disk backups, communications, etc., without
  280. any operator intervention. When all is done, a command can be
  281. called to turn the computer off (XA "COMPUTER OFF").  All this
  282. can take place while you sleep.  This is what automation is all
  283. about.  For more  information, refer to the section - "Powerup
  284. Utility".
  285.  
  286.  
  287. FINDX10.EXE 
  288. ─────────────────────────────────────────────────────────────────────
  289.  
  290. This new utility is provided to help you determine the
  291. configuration of the serial port your CP-290 is connected to.
  292. After FINDX10 searches all COM ports in your system, it
  293. determines the address and IRQ of the port and attempts to
  294. communicate with the CP-290. If it successfully  locates the
  295. CP-290, it displays the port setup and prompts you if it is OK
  296. to save the data in your XA.INI file.
  297.  
  298.  
  299. ═════════════════════════════════════════════════════════════════════
  300. 5.   Installation 
  301. ═════════════════════════════════════════════════════════════════════
  302.  
  303. First, copy the contents of this floppy to the same drive and
  304. directory in which your X10 software resides.  For example, if
  305. your X10 files are located on Drive C in the directory "X10",
  306. and the XA installation floppy disk is inserted in Drive A, you
  307. would type at the DOS prompt:
  308.  
  309.      C:
  310.      CD \X10
  311.      COPY A:\*.* C:          
  312.  
  313. If you haven't already done so, include this drive and directory
  314. within your PATH statement of the AUTOEXEC.BAT file.  The "PATH"
  315. statement tells DOS where to locate frequently used executable
  316. files.
  317.  
  318.      SET PATH=C:\DOS;C:\X10;...
  319.  
  320. You should set the XA environment variable to the drive and
  321. directory of your command files.  This environment variable,
  322. which can also be placed in your AUTOEXEC.BAT file, tells XA
  323. where to find its  initialization and command files.
  324.  
  325.      SET XA=C:\X10
  326.  
  327. If you don't understand the concepts of the PATH or SET command,
  328. refer to your DOS User's Guide and Reference manual. Also, see
  329. the AUTOEXEC.BAT supplied with this package for an example.
  330.  
  331. Finally, let XA's utility program "FINDX10" search your
  332. computer's serial ports for the CP-290. FINDX10 will determine
  333. the IO port address and IRQ (interrupt vector) for that
  334. particular port. These parameters are important for the
  335. successful operation of XA. If the CP-290 is located, you will
  336. be prompted if it's OK for FINDX10 to write those parameters
  337. into your XA.INI initialization file. Enter 'Y' for YES if you
  338. agree with these values.  You can always edit these statements
  339. later. See the chapters dealing with XA.INI - INITIALIZATION
  340. FILE, and FINDX10.EXE later in this manual for more details.
  341.  
  342.  
  343. ═════════════════════════════════════════════════════════════════════
  344. 6.   Getting Started 
  345. ═════════════════════════════════════════════════════════════════════
  346.  
  347. XA may be invoked several different ways.  How you configured
  348. XA, or the types of parameters that you use with it, determine
  349. how XA behaves.
  350.  
  351. Method 1 - The "HELP" screen.
  352. ─────────────────────────────────────────────────────────────────────
  353.  
  354. At the DOS prompt, enter:
  355.  
  356.      XA
  357.  
  358. XA will display the first of many different "help" screens.
  359. These screens include a brief synopsis of XA, and a list of
  360. available commands that it recognizes.
  361.  
  362. NOTE: This method will not work if the token XACMD is defined in
  363. your XA.INI file. The default XA.INI file shipped on this floppy
  364. will have XACMD "commented out" (or undefined).   
  365.  
  366.  
  367. Method 2 - The "HELP" screen.
  368. ─────────────────────────────────────────────────────────────────────
  369.  
  370. At the DOS prompt, enter:
  371.  
  372.      XA /?
  373.      XA /H
  374.      XA /h
  375.  
  376. Again, XA will display the first of many different "help"
  377. screens.  Use this method if your XA.INI file utilizes the XACMD
  378. token and you wish to see the help screens.
  379.  
  380.  
  381. Method 3 - Executing a DIRECT Command from DOS.
  382. ─────────────────────────────────────────────────────────────────────
  383.  
  384. At the DOS prompt, enter:
  385.  
  386.      XA "A1 OFF"
  387.  
  388. The above is a direct command which sends an X10 Off command to
  389. the module with a House-Unit code of A1. Direct commands are
  390. always executed immediately. 
  391.  
  392.  
  393. Method 4 - Storing an EVENT into the CP-290's memory via DOS.
  394. ─────────────────────────────────────────────────────────────────────
  395.  
  396. At the DOS prompt, enter:
  397.  
  398.      XA "A1 ON MONDAY SUNSET"
  399.  
  400. XA will determine which event slot is available in the CP-290's
  401. memory. The event will be downloaded for later execution. 
  402. Events are distinguished from direct commands by the fact that
  403. events normally contain a DAY modifier (in this case MONDAY -
  404. but you could also use TODAY or TOMORROW) and a TIME modifier
  405. (SUNSET is a special TIME token). 
  406.  
  407.  
  408. Method 5 - Executing a Command File
  409. ─────────────────────────────────────────────────────────────────────
  410.  
  411. At the DOS prompt, enter:
  412.  
  413.      XA f=XA.CMD
  414.  
  415. The file XA.CMD contains a series of EVENT or DIRECT command
  416. statements.  These statements are either executed immediately as
  417. they are parsed, or sent to the CP-290 to be activated at some
  418. future time. 
  419.  
  420.  
  421.  
  422. ═════════════════════════════════════════════════════════════════════
  423. 7.   XA Syntax and Command Line Arguments
  424. ═════════════════════════════════════════════════════════════════════
  425.  
  426. XA understands the following command line options:
  427.  
  428.       XA ["commands"...] [f=filename] [-e] [+l] [+m] [+p] [-p] 
  429.         [+r1] [+r2] [c=comm port] [i=irq] [o=io_addr] [/?]  
  430.  
  431. Options appearing on the command line always override any
  432. options that have been specified in XA's command and
  433. initialization files.  This gives you the final "say" when
  434. overriding defaults.
  435.  
  436. Options and commands are parsed from left to right. Under normal
  437. circumstances, options may appear in any order without any
  438. conflict.  Many of these options have equivalent tokens that can
  439. be embedded within a command file or the XA initialization file
  440. (XA.INI). Therefore, you won't have to specify these options
  441. every time you execute XA.
  442.  
  443.  
  444. ["commands"]
  445.   "commands" consist of one or more tokens (see "Tokens" later in
  446.   this document) that describe an event or direct command.  When
  447.   you send a DIRECT command or EVENT via the DOS command line, a
  448.   command consisting of several tokens must be enclosed in
  449.   "quotation marks".   The quotation marks inform XA to treat the
  450.   tokens as a group, not individual commands. For example:
  451.  
  452.      XA "A1 ON"
  453.  
  454.   In the above example, A1 and ON are tokens. Together they form a
  455.   single command.  Multiple commands may appear in the command
  456.   line as long as they are enclosed in their own quotation marks. 
  457.   The next example shows the use of multiple commands to create a
  458.   flashing effect.
  459.  
  460.      XA "A1 ON" "A1 OFF" "A1 ON" "A1 OFF"
  461.  
  462.  
  463. [f=filename] 
  464.   This is the name of the file containing the commands to be
  465.   interpreted by XA.  To use XA in its file mode with a command
  466.   file called MONITOR.CMD, you would type:
  467.  
  468.      XA f=monitor.cmd
  469.  
  470.   Commands contained in files do not have to be enclosed in
  471.   "quotation marks".
  472.  
  473.   You can specify a default command file using the "XACMD" token
  474.   in the XA.INI initialization file (described in greater detail
  475.   later).
  476.  
  477.   See also: 
  478.      Miscellaneous tokens: XACMD
  479.      XA.INI - Initialization file
  480.  
  481.  
  482. [-e]
  483.   This option is used to prevent any communications to the
  484.   interface.  When you use this option, the parser verifies every
  485.   statement, but does not send any event information or direct
  486.   commands to the CP-290.  Use this option for testing new command
  487.   files. 
  488.  
  489.  
  490. [c=comm_port]
  491.   This allows you to select the serial port for communications
  492.   with the interface.  You may select ports 1...4. For example, if
  493.   your CP-290 is connected to COM3:
  494.  
  495.      XA c=3
  496.  
  497.   If not specified, the default port will be COM1.  
  498.  
  499.   When using this option, you are actually specifying both an IO
  500.   address as well as the IRQ vector for this port. See the table
  501.   listed in the "Communications Tokens" section, later in this
  502.   document.  
  503.  
  504.   See also:
  505.      Communication tokens: COM1...COM4
  506.      Command Line options: [o=io_addr]
  507.  
  508.  
  509. [o=io_addr] 
  510.   This option allows you to select a different IO address from the
  511.   default 3F8 hex.  If your serial port is setup for 2E8 hex, then
  512.   use:
  513.  
  514.       XA o=2E8H
  515.  
  516.   See also:
  517.      Communication tokens: IO x
  518.  
  519.  
  520. [i=irq]
  521.   Interrupt-driven: i=irq (3,4,5...)  
  522.  
  523.   Default: i=4  (for COM1).
  524.  
  525.   See also:
  526.      Communication tokens: IRQ x
  527.  
  528.  
  529. [+m] 
  530.   This option will monitor the comm port for any events reported
  531.   by the CP-290.  Press the <ESC> key to terminate. 
  532.  
  533.   See also:
  534.      Reporting tokens: MONITOR     
  535.      "Monitoring and Logging Events"
  536.  
  537.  
  538. [+l]
  539.   This option will append any monitoring information to the file
  540.   XA.LOG.  The report file will be saved on the same drive and
  541.   directory as was specified by the XA environment variable
  542.   (discussed in "Installation").
  543.  
  544.   See also:
  545.      Reporting tokens: LOG     
  546.      "Monitoring and Logging Events"
  547.  
  548.      
  549. [+r1]
  550.   This option will produce a report file (called XA.RPT) of all
  551.   events that were just processed by the interpreter.  The format
  552.   of the report contains a sorted list of events (based on time)
  553.   for each day of the week.
  554.  
  555.   See also:
  556.      Reporting tokens: REPORT1
  557.      "Report Files"
  558.  
  559.  
  560. [+r2]
  561.   This option will produce a report file (called XA.RPT) of all
  562.   events just processed by the interpreter.  The format of the
  563.   report contains a sorted list of events (based on time), for
  564.   each module, for each day of the week.  The report file will be
  565.   saved on the same drive and directory as was specified by the XA
  566.   environment variable (discussed in "Installation").  Any
  567.   existing reports called XA.RPT will be overwritten.  You may
  568.   specify both report types to be included in the same file, as in
  569.   the following example.
  570.  
  571.      XA +r1 +r2
  572.  
  573.   See also:
  574.      Reporting tokens: REPORT2     
  575.      "Report Files"
  576.  
  577.  
  578. [+p]
  579.   Parses command file, then performs powerfail recovery. 
  580.  
  581. [-p]
  582.   Immediate recovery based on stored events, no parsing of command
  583.   file takes place.
  584.  
  585.   Powerfail recovery allows you to restore each module to its
  586.   scheduled state. By default, XA uses the last 7 days to
  587.   determine the state.  You can tell XA to use fewer days if
  588.   necessary. Simply append a number between 1and 6 to the command.
  589.   If you want XA to review the event schedule of the previous 2
  590.   days in order to determine the correct state, then append a 2 to
  591.   the command, for example:
  592.  
  593.      XA -p2
  594.  
  595.   Use "-e" in conjunction with either "+p" or "-p" to see how XA
  596.   would restore each module without actually sending any X10
  597.   commands.
  598.  
  599.   See also:
  600.      "Powerfail Recovery"
  601.  
  602.      
  603. [/?]
  604. [/h]
  605. [/H]
  606.   Displays a summary of the options described above, along with a
  607.   list of all supported tokens recognized by the interpreter.
  608.  
  609.  
  610.  
  611. ═════════════════════════════════════════════════════════════════════
  612. 8.   XA Tokens 
  613. ═════════════════════════════════════════════════════════════════════
  614.  
  615. What are tokens?
  616.  
  617. A token is to an X10 command as a word is to an English
  618. sentence.  Individual words are constructed to form a complete
  619. sentence - tokens are constructed to form a complete command. 
  620. This section will describe each token that is recognized by the
  621. interpreter. Some tokens may appear anywhere in the command. 
  622. For example, the command
  623.  
  624.      XA "A1 ON"    may also be constructed as:        
  625.      XA "ON A1"
  626.  
  627. In other instances, tokens must be arranged in groups.  Their
  628. order is important.  For example, the command to set your PC's
  629. internal clock to the time that is maintained by the CP-290 is:
  630.  
  631.      XA "SYNCHRONIZE PC"      <---This is legal
  632.  
  633. If the tokens SYNCHRONIZE and PC were reordered as in the
  634. following command:
  635.  
  636.      XA "PC SYNCHRONIZE"      <---This is illegal
  637.  
  638. The interpreter would respond with a message indicating the
  639. token it did not recognize the token. Therefore, throughout this
  640. documentation any tokens that must be arranged in a certain
  641. order will be contained in curly braces {..}.  Other tokens may
  642. be optional and will be contained in parentheses (..).
  643.  
  644. Most or the examples in the next chapter describe how the tokens
  645. may be used from the DOS command line. Therefore, the tokens
  646. that make up a complete command will be enclosed in "quotation
  647. marks".  Other examples show how the tokens may be used in a
  648. file, therefore, quotation marks are not used, or needed. 
  649.  
  650.  
  651. ═════════════════════════════════════════════════════════════════════
  652. 9.   Tokens in Detail 
  653. ═════════════════════════════════════════════════════════════════════
  654.  
  655. Action Tokens 
  656. ─────────────────────────────────────────────────────────────────────
  657.  
  658.   ON
  659.      This token informs the interface to turn ON the selected modules.
  660.  
  661.         XA "A1 ON"
  662.  
  663.  
  664.   OFF
  665.      This token informs the interface to turn OFF the selected
  666.      modules.
  667.  
  668.         XA "A1 OFF"
  669.  
  670.  
  671.   {DIM %%}
  672.      These two tokens specify the intensity level of the selected
  673.      lamp or wall switch module.  The modules will turn on, brighten
  674.      to full intensity, then dim to the percentage specified in the
  675.      second token.  There are 16 different brightness levels
  676.      available, the percentage you choose (0 to 100) is mapped to one
  677.      of these levels. The percentage level you select may not
  678.      correspond exactly with level reported by the X10-supplied
  679.      program X10.EXE.
  680.  
  681.         XA "A1 DIM 50"
  682.  
  683.  
  684.   {ALL_UNITS_OFF HOUSE x}
  685.      These tokens will issue the X10 "ALL_UNITS_OFF" command for the
  686.      selected housecode. This command affects Appliance-style and
  687.      Lamp Dimmer/Wall Switch modules.
  688.  
  689.         XA "ALL_UNITS_OFF HOUSE A"
  690.  
  691.      Using this command is faster than issuing (as described in the
  692.      next section):
  693.  
  694.         XA "HOUSE A UNIT ALL OFF" 
  695.  
  696.  
  697.   {ALL_LIGHTS_ON HOUSE x}
  698.      These tokens will issue the X10 "ALL_LIGHTS_ON" command for the
  699.      selected housecode. This command affects only Lamp Dimmer/Wall
  700.      Switch modules. 
  701.  
  702.         XA "ALL_LIGHTS_ON HOUSE A"
  703.  
  704.  
  705.  
  706.      Notes:
  707.       * Only one token in this category should appear in a command. If
  708.         two or more of these tokens appear, only the last one will be
  709.         processed.  For example:
  710.  
  711.            XA "A1 ON OFF"  -  will be interpreted as:        
  712.            XA "A1 OFF"
  713.  
  714.         If you were trying to flash the lights, the proper way to
  715.         perform this action is:
  716.  
  717.            XA "A1 ON"  "A1 OFF"
  718.  
  719.       * You may activate as many modules as you want in a single command
  720.         providing these modules share the same HOUSE code:
  721.  
  722.            XA "A1 A2 A3 A4 A5 A6 ON"
  723.  
  724.       * To activate modules with different HOUSE codes, use separate
  725.         commands:
  726.  
  727.            XA "A1 A2 A3 ON"  "B1 B2 ON"  "C1 OFF"
  728.  
  729.  
  730.  
  731. Module Address Tokens 
  732. ─────────────────────────────────────────────────────────────────────
  733.  
  734.   A1...P16
  735.      This is a shortcut method of specifying both HOUSE and UNIT
  736.      tokens.  The house code must appear first, followed by  the unit
  737.      code.  Specifying ALL is not permitted.
  738.  
  739.         XA "A1 ON"  "P16 OFF"
  740.  
  741.  
  742.   {HOUSE x}
  743.      These two tokens specify the HOUSE code of the module you want
  744.      to select.  There are 16 HOUSE codes available,  lettered A
  745.      through P.  This method of selecting addresses requires the use
  746.      of the UNIT token.  Only one HOUSE token should appear in a
  747.      command.
  748.  
  749.  
  750.   {UNIT y}
  751.   {UNIT ALL}
  752.      These two tokens specify the UNIT code of the module you want to
  753.      select.  There are 16 UNIT codes available, numbered 1 through
  754.      16.  Specifying UNIT ALL operates on all 16 modules addressed by
  755.      the HOUSE token.  This method of module addressing requires the
  756.      use of the HOUSE token:  
  757.  
  758.         XA "HOUSE A UNIT 1 ON"   or,   
  759.         XA "UNIT 1 HOUSE A ON"
  760.  
  761.      Multiple UNITs may appear in a single command:
  762.  
  763.         XA "HOUSE A UNIT 1 UNIT 2 UNIT 3 ON"
  764.  
  765.      Turn off all units on HOUSE P:
  766.  
  767.         XA "HOUSE P UNIT ALL OFF"     or use the faster method:
  768.         XA "HOUSE P ALL_UNITS_OFF"
  769.  
  770.  
  771.      Notes:
  772.       * You may activate as many modules as you want in a single command
  773.         providing these modules share the same HOUSE code:
  774.  
  775.            XA "A1 A2 A3 A4 A5 A6 ON"
  776.  
  777.       * To activate modules with different HOUSE codes, use separate
  778.         commands:
  779.  
  780.            XA "A1 A2 A3 ON"  "B1 B2 ON"  "C1 OFF"
  781.  
  782.       * You can give your module's more descriptive names by using the
  783.         DEFINE token (described later). For instance, place the
  784.         following line in your XA.INI file:
  785.  
  786.            DEFINE COFFEE HOUSE A UNIT 10
  787.            
  788.         To turn the coffee pot ON from your computer, all you have to
  789.         type is:
  790.  
  791.            XA "COFFEE ON" or   
  792.            XA "A10 ON"
  793.  
  794.  
  795. Coordinate Tokens 
  796. ─────────────────────────────────────────────────────────────────────
  797.  
  798. This group of tokens enable the precise calculation of sunrise
  799. and sunset times for your location.  This information can be
  800. found in almanacs, or extrapolated from maps.  Coordinates for
  801. major U.S. cities may be found in the file US_LATIT.TXT supplied
  802. with XA. Your local library or city hall may also have your
  803. city's precise coordinates.  These tokens should be placed in
  804. your XA.INI file so that all command files will be able to
  805. calculate sun-related events. 
  806.  
  807.   {LATITUDE dms}
  808.   {LATITUDE ° ' "}
  809.      Your latitude in degrees (0...+/-90), minutes (0...59) and, 
  810.      optionally, seconds (0...59).
  811.  
  812.         LATITUDE 41d35m20s   -or-        
  813.         LATITUDE 41°35'20"
  814.  
  815.  
  816.   {LONGITUDE dms}
  817.   {LONGITUDE ° ' "}
  818.      Your longitude in degrees (0...+-180), minutes (0...59) and,
  819.      optionally, seconds. Longitudes West of the prime meridian are
  820.      positive, those East of the prime meridian are negative.  In the
  821.      US, all longitudes are positive.
  822.  
  823.         LONGITUDE 81d20m45s     -or-        
  824.         LONGITUDE 81°20'45"
  825.  
  826.  
  827.   {TIMEZONE x}
  828.      Exact calculations depend on the local time.  Use the following
  829.      table to determine your time zone. Previous versions of XA
  830.      included "Daylight Savings" values in this table. It is no
  831.      longer necessary to manually change these tokens. Use the DST
  832.      token to automatically adjust time changes.
  833.  
  834.                ZONE      TIMEZONE 
  835.            ============= ========
  836.            Eastern           5 
  837.            Central           6 
  838.            Mountain          7 
  839.            Pacific           8 
  840.            Alaska/Hawaii    10 
  841.            Aleutian         11 
  842.  
  843.         TIMEZONE 5
  844.  
  845.  
  846.   DST
  847.      Use the token DST to have XA determine when changes for Daylight
  848.      Savings or Standard Time should go into effect. This means you
  849.      only have to specify a single timezone token in your
  850.      initialization file  (XA.INI).
  851.  
  852.         TIMEZONE 5  DST
  853.  
  854.  
  855.  
  856. Clock Tokens 
  857. ─────────────────────────────────────────────────────────────────────
  858.  
  859.   {SYNCHRONIZE PC (EXACT)}
  860.      These tokens instruct XA to set your computer's clock based on
  861.      the current time retrieved from the CP-290.  It will not affect
  862.      the computer's date.
  863.  
  864.         XA "SYNCHRONIZE PC"
  865.  
  866.      Use the optional "EXACT" token to wait for the X10 time to
  867.      rollover to the next minute.  This provides a synchronization
  868.      within 1 second, but forces you to wait for up to one minute for
  869.      this rollover to happen.
  870.  
  871.         XA "SYNCHRONIZE PC EXACT"
  872.  
  873.  
  874.   {SYNCHRONIZE X10 (EXACT)}
  875.      These tokens instruct XA to set the time and day of the CP-290
  876.      internal clock based on the current time retrieved from your
  877.      computer.
  878.  
  879.         XA "SYNCHRONIZE X10"
  880.  
  881.      Using "EXACT" will force XA to wait until the PC's clock to
  882.      rollover to the next minute.  This provides a synchronization
  883.      within 1 second, but forces you to wait for up to one minute for
  884.      this rollover to happen.
  885.  
  886.         XA "SYNCHRONIZE X10 EXACT"
  887.  
  888.      Notes:
  889.       * You might want to include the command XA "SYNCHRONIZE PC" in
  890.         your AUTOEXEC.BAT file to set your PC's internal clock if your
  891.         system lacks an on-board battery backed-up clock.  Note that
  892.         this command will not set up the date since the CP-290 does not
  893.         contain a real-time calendar.
  894.  
  895.       * Use XA "SYNCHRONIZE PC" or XA "SYNCHRONIZE X10" in your
  896.         AUTOEXEC.BAT file if either your PC or CP-290 does not keep
  897.         accurate time. 
  898.  
  899.  
  900.  
  901. Day Tokens 
  902. ─────────────────────────────────────────────────────────────────────
  903.  
  904. Use of these tokens indicates a timed event, i.e., the complete
  905. command will be downloaded to the interface and stored there for
  906. later activation.
  907.  
  908.   SUNDAY, SUN 
  909.   MONDAY, MON
  910.   TUESDAY, TUE
  911.   WEDNESDAY, WED
  912.   THURSDAY, THU
  913.   FRIDAY, FRI
  914.   SATURDAY, SAT
  915.      These tokens describe the specific day of the event. Multiple
  916.      tokens may appear within a command.
  917.  
  918.         XA "MONDAY FRIDAY A1 ON TIME 7:30 AM"
  919.  
  920.   WEEKENDS, WEEKEND
  921.      Event occurs on SATURDAY and SUNDAY.
  922.  
  923.   WEEKDAYS, WEEKDAY
  924.      Event occurs MONDAY TUESDAY WEDNESDAY THURSDAY  FRIDAY.
  925.  
  926.   EVERYDAY
  927.      Event occurs MON TUE WED THU FRI SAT SUN.
  928.  
  929.   TODAY
  930.      Event will occur today only at the specified time.  It is then
  931.      deleted from the interface after midnight.  If "OFFSET hh:mm" is
  932.      also programmed causing the event to trigger after midnight, the
  933.      event will be modified for TOMORROW status.
  934.  
  935.   TOMORROW
  936.      Event will occur tomorrow only at the specified time.  It is
  937.      then deleted from the interface after midnight.  If "OFFSET
  938.      hh:mm" is also programmed causing the event to trigger before
  939.      midnight, the event  will be modified for TODAY status.  
  940.  
  941.   Notes:
  942.    * If you leave off a DAY token when downloading an event to the
  943.      CP-290, XA will assign the command as a TODAY-only event.
  944.      Therefore, at midnight the event will be cleared from XA's
  945.      memory. The following command will take place at 11:00 tonight
  946.      and be deleted at midnight since it was given "TODAY" status (no
  947.      other DAY was specified):
  948.  
  949.         XA "FAN ON TIME 11:00 PM"
  950.  
  951.    * Registered Users - Using the "CDAY" token in conjunction with
  952.      "SAT,SUN MON, TUE, WED, THU, FRI, WEEKEND, WEEKDAY" tokens
  953.      allows you to program special functions based on the current
  954.      day. For example, the statements below will the initialize the
  955.      default command file (using XACMD) based on the current day.
  956.      Note: Use of the IF/ELSE/ENDIF and CDAY tokens, as well as the
  957.      "==" and "OR" operators will be discussed later in this 
  958.      document.
  959.  
  960.         IF ((CDAY == SAT) OR (CDAY == SUN))
  961.            XACMD WEEKEND.CMD
  962.         ELSE
  963.            XACMD WEEKDAY.CMD
  964.         ENDIF
  965.  
  966.  
  967. Specific Date Tokens
  968. ─────────────────────────────────────────────────────────────────────
  969.  
  970. Since the CP-290 does not contain an on-board calendar, there is
  971. no direct method of storing an event that occurs more than 1
  972. week away.  However, XA has the ability to evaluate dates and as
  973. long as XA is run at least once a week it can determine the
  974. appropriate time to download the event.  This feature allows you
  975. specify an event weeks, months, or years in advance.
  976.  
  977. Date features:
  978.    * You can specify an event to occur on specific days of each month
  979.      (such as every 10th day of the month), or annually (every 4th of
  980.      July)
  981.  
  982.    * Events may be scheduled to trigger on selected days between
  983.      specific dates (such as Christmas and New Year's).  You can also
  984.      program an event to NOT happen on an individual date, or between
  985.      certain dates.
  986.  
  987. To guarantee that specific dates will be evaluated and events
  988. will be triggered at the proper time in the future, plug your
  989. computer into an Appliance module and have the CP-290 turn your
  990. computer on automatically on a once-per-week basis.  By using
  991. XA.EXE in conjunction with POWERUP.EXE (supplied with this
  992. package) you can have a new set of events automatically
  993. downloaded to the CP-290. Now you'll never forget to update your
  994. CP-290, your computer  does it for you automatically.  This is
  995. what "automation" is all about.  See  section "Powerup" for more
  996. details.
  997.  
  998. When using the following "DATE" tokens, you should include the
  999. "ERASE" token at the beginning of your command file.  ERASE will
  1000. clear the entire contents of the CP-290, removing all event 
  1001. information. The reason you want to erase its memory is because
  1002. once XA downloads an event to the CP-290, it will remain there
  1003. until it is deleted or overwritten.  The next time XA is run
  1004. (next week) the event may still remain and trigger itself again
  1005. and again until it is either manually deleted, or eventually
  1006. overwritten by a new event. ERASE ensures that the data is
  1007. cleared and that the interface will contain fresh information. 
  1008. Also, since all your information is stored in a command file,
  1009. the relevant information will always be placed in the CP-290.
  1010.  
  1011.  
  1012.   {DATE mm/dd/yyyy}
  1013.      Event occurs on specified date.  You must specify the date in
  1014.      the following format:
  1015.  
  1016.      Month - none, 1, or 2 digits (1 = Jan ...  12 = Dec)
  1017.      Day   - none, 1, or 2 digits     
  1018.      Year  - none, or 4 digits (1994 - NOT 94).
  1019.  
  1020.      To specify module A5 ON July 4, 1994 at 5:00 pm:
  1021.         
  1022.         A5 ON DATE 7/4/1994 TIME 5:00 PM
  1023.  
  1024.      You may omit fields which is the equivalent of specifying any
  1025.      month, day, or year.  Each field must be delineated by a
  1026.      separator, either a '/' or '-' character.   For example, to
  1027.      specify module A5 to turn OFF on the 4th of every month at 6:00 AM:
  1028.  
  1029.         DATE /4/ A5 OFF TIME 6:00 AM
  1030.  
  1031.      To specify module A5 to turn ON every 4th of July at sunset,
  1032.      leave off the "yyyy" field:
  1033.  
  1034.         DATE 7/4/ A5 ON SUNSET
  1035.  
  1036.      An exception to the separator requirement arises when the "yyyy"
  1037.      is not being programmed -simply omit the '/' or '-' character
  1038.      between the "dd" and "yyyy" fields. The above statement could be
  1039.      written as:
  1040.  
  1041.         DATE 7/4 A5 ON SUNSET
  1042.  
  1043.      You may specify multiple dates in the same command:
  1044.  
  1045.         DATE 7/4 DATE 7/6 DATE 7/8 A5 ON SUNSET
  1046.  
  1047.  
  1048.   {DATE mm/dd/yyyy THRU mm/dd/yyyy (DAY)}
  1049.      Event will occur EVERYDAY between the two dates unless you place
  1050.      specific DAY tokens within the command.  Use the same date
  1051.      format conventions as described above.
  1052.  
  1053.      If you will be going on vacation between July 1, 1994 and August
  1054.      1, 1994, and you want the bedroom lights (A3) turned ON and OFF
  1055.      every weekday in a random fashion during the evenings:
  1056.  
  1057.         DATE 7/1/1994 THRU 8/1/1994  ON A3 TIME 9:00 PM SECURITY WEEKDAYS
  1058.         DATE 7/1/1994 THRU 8/1/1994 OFF A3 TIME 11:30 PM WEEKDAYS
  1059.  
  1060.      To turn ON your Christmas lights everyday between Dec. 1st and
  1061.      Jan. 1st. Turn them OFF at 10:00PM on weekdays, turn them off at
  1062.      11:30 during the weekends:
  1063.  
  1064.         DATE 12/1 THRU 1/1 XMAS ON SUNSET
  1065.         DATE 12/1 THRU 1/1 XMAS OFF TIME 10:00 PM WEEKDAYS
  1066.         DATE 12/1 THRU 1/1 XMAS OFF TIME 11:30 PM WEEKENDS
  1067.  
  1068.  
  1069.   EXCEPT
  1070.      Once XA parses this token, any DATE (or DATE...THRU) statements
  1071.      become "exceptions", that is, events will not be scheduled to
  1072.      activate during that date (or period). For example, to turn a
  1073.      lamp (A7) on every weeknight except Memorial Day:
  1074.  
  1075.         A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31
  1076.  
  1077.      You may specify multiple exception dates in the same command:
  1078.  
  1079.         A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31 DATE 7/1
  1080.  
  1081.  
  1082.      Notes:
  1083.       - Use the format:
  1084.  
  1085.       {EXCEPT DATE mm/dd/yyyy THRU mm/dd/yyyy (DAY)}
  1086.         to prevent an event from occurring between two dates. EVERYDAY
  1087.         will be assumed unless you place specific DAY tokens within the
  1088.         command.  For example, to prevent the porch lights from coming
  1089.         on while your Christmas lights are on:
  1090.  
  1091.            PORCH ON SUNSET EXCEPT DATE 12/1/1994 THRU 1/1/1995
  1092.  
  1093.         Special Note: When dates "rollover" into the next year, you must
  1094.         specify the "year" within the date statement (as in the above
  1095.         example). 
  1096.  
  1097.      - Use the format:
  1098.  
  1099.      {DATE mm/dd/yyyy THRU mm/dd/yyyy EXCEPT DATE mm/dd/yyyy THRU mm/dd/yyyy} 
  1100.         to specify a range of dates that a module should not activate,
  1101.         within a range of dates that they should be activated.  For
  1102.         instance, turn on deck lights only during the summer, except
  1103.         while you are on  vacation:
  1104.  
  1105.            DECK ON SUNSET DATE 6/21 THRU 9/22 EXCEPT DATE 7/1 THRU 7/14
  1106.  
  1107.            
  1108. Time Tokens
  1109. ─────────────────────────────────────────────────────────────────────
  1110.  
  1111. Use of these tokens indicate a timed event, i.e., the complete
  1112. command will be downloaded to the interface and stored there for
  1113. later activation.
  1114.  
  1115.   {TIME hh:mm (AM/PM)}
  1116.      Schedule event at a certain time.
  1117.  
  1118.         XA "D1 ON SUNDAY TIME 12:30 AM"
  1119.  
  1120.      AM is the default. You may specify military-style time as
  1121.      follows:
  1122.  
  1123.         XA "D1 ON SUNDAY TIME 23:34 "
  1124.  
  1125.  
  1126.   SUNRISE
  1127.   SUNSET
  1128.      These tokens will calculate the sunrise or sunset for the day
  1129.      token in the command.  The use of these tokens also requires the
  1130.      LATITUDE, LONGITUDE, and TIMEZONE (and optional DST) tokens to
  1131.      be included in  the XA.INI file. 
  1132.  
  1133.         D1 ON MONDAY SUNSET
  1134.  
  1135.      If multiple day tokens appear in the command line, the sunrise
  1136.      or sunset time will be the average sunrise/set time for the next
  1137.      seven days. 
  1138.  
  1139.         MONDAY TUESDAY WEDNESDAY ON SUNSET D1
  1140.  
  1141.      If more accuracy is needed, then break each daily event into its
  1142.      own command.
  1143.  
  1144.         MONDAY ON SUNSET D1
  1145.         TUESDAY ON SUNSET D1
  1146.         WEDNESDAY ON SUNSET D1
  1147.  
  1148.  
  1149.   {OFFSET +/-hh:mm}
  1150.   {OFFSET +/-mins}
  1151.      Push or postpone the scheduled event by up to 24 hours (1440
  1152.      minutes).  This token is useful if you want to activate lights
  1153.      at dusk rather than sunset, or to deactivate lights at dawn
  1154.      rather than sunrise.  The '+' sign is the default condition, you
  1155.      must specify the  '-' if needed.  To turn ON lights 30 minutes
  1156.      after sunset:
  1157.  
  1158.         MONDAY ON SUNSET D1 OFFSET 30
  1159.  
  1160.      Turn lights OFF 1 hour before sunrise:
  1161.  
  1162.         MONDAY OFF SUNRISE D1 OFFSET -1:00
  1163.  
  1164.      See section Miscellaneous Tokens - DEFINE for another way of 
  1165.      specifying DUSK or DAWN using the DEFINE token.  For example:
  1166.  
  1167.         DEFINE DUSK SUNSET OFFSET 30
  1168.         DEFINE DAWN SUNRISE OFFSET -1:00
  1169.                 :
  1170.         MONDAY ON DUSK D1
  1171.         MONDAY OFF DAWN D1
  1172.  
  1173.  
  1174.   {NOW +mm}
  1175.   {NOW +hh:mm}
  1176.      Creates a one-shot event based on the current DOS day and time
  1177.      and the hh:mm offset specified in the token. The event will
  1178.      initially be given a "TODAY" status.  If the added offset causes
  1179.      the event to be scheduled past midnight, the event will be
  1180.      converted to "TOMORROW" status.  In either case, the event will
  1181.      be deleted from the CP-290 at midnight following its activation.
  1182.  
  1183.      The following command file example shows how to activate a
  1184.      battery charger and then turn it off 14 hours later. This file
  1185.      is called CHARGER.CMD.
  1186.  
  1187.         DEFINE CHARGER H1
  1188.         CHARGER ON             # Turn the charger on...
  1189.         CHARGER OFF NOW 14:00  # Have the CP-290 turn it off 14 hours later
  1190.  
  1191.      Earlier versions of XA required the use of the EVENT token in
  1192.      order to prevent overwriting existing events in the CP-290's
  1193.      memory.  XA Version 2.0 automatically appends the command to
  1194.      current schedule,  eliminating the need to figure this out
  1195.      manually.
  1196.  
  1197.  
  1198.   NORMAL
  1199.      This token activates the event at the specified time.  It is the
  1200.      default mode, therefore it does not need to be specified.
  1201.  
  1202.  
  1203.   {RANDOM +/-hh:mm}
  1204.   {RANDOM +/-mins}
  1205.      Prior to Version 1.07, RANDOM used to be synonymous with the
  1206.      SECURITY token, which merely activated the CP-290 built-in time
  1207.      adjustment.  This feature would pseudo-randomly select a time
  1208.      for event activation anytime within the programmed hour.  
  1209.      "RANDOM hh:mm" now gives you complete control over the random
  1210.      window.  "hh:mm" is the number of hours and minutes that a
  1211.      random offset should be added/subtracted from the programmed
  1212.      time. This offset should be in the range of 1 minute to 24 hours
  1213.      (1440  mins).  If "hh:mm" is programmed with a "+" sign, then
  1214.      the calculated random value will be added to the programmed
  1215.      time. The following example will add between 0 and 9 minutes to
  1216.      the requested time, that is, anywhere between 5:00 PM and 5:09 PM.
  1217.  
  1218.         A5 ON TIME 5:00 PM RANDOM +9
  1219.  
  1220.      If "mm" is programmed with a "-" sign, then the calculated
  1221.      random value will be subtracted from the programmed time. The
  1222.      following example will subtract between 0 and 15 minutes from
  1223.      the calculated SUNRISE time. If SUNRISE occurs at 6:00 AM, then
  1224.      the resulting time could be anywhere in the range of 5:45
  1225.      through 6:00.
  1226.  
  1227.         SUNRISE RANDOM -:15
  1228.  
  1229.      If "mm" is programmed without any sign, then the calculated
  1230.      random value will either be added or subtracted to/from the
  1231.      programmed time.  For example, to allow 90 minutes of either
  1232.      side of SUNSET:
  1233.      
  1234.                                 # Sunset @ 9:00 PM
  1235.         SUNSET RANDOM 1:30       # TIME ranges between 7:30 PM ... 10:30 PM
  1236.  
  1237.      RANDOM, as well as OFFSET, will automatically change the day if
  1238.      the adjustment causes a rollover into the previous or next day.
  1239.  
  1240.  
  1241.   SECURITY
  1242.      This token allows the CP-290 to randomly select the activation
  1243.      time of the event.  This activation occurs within the hour of
  1244.      the programmed time.  Therefore, if the downloaded time was for
  1245.      7:18 PM, actual activation time could range from 7:00 PM through
  1246.      7:59 PM. This mode provides a security feature giving your
  1247.      lighting a more lived-in look.
  1248.  
  1249.         XA "A1 ON TIME 7:30 PM SECURITY EVERYDAY"
  1250.         
  1251.  
  1252.         
  1253. Direct Command Control Tokens
  1254. ─────────────────────────────────────────────────────────────────────
  1255.  
  1256. The following tokens may be used within an XA command file so
  1257. you can use the CP-290 to perform a series of lighting effects.
  1258. Certain commands may be repeated a limited number of times or
  1259. forever.  Commands may also be synchronized with a key press,
  1260. allowing special effects with a high degree of accuracy.  The
  1261. "registered" version of XA can also read data from an I/O port,
  1262. allowing X10 commands to be synchonized with an external event.
  1263.  
  1264.  
  1265.   PAUSE
  1266.      When this token is executed, it displays a message and halts
  1267.      further execution of the command file.:
  1268.  
  1269.         "Press any key to continue..."
  1270.  
  1271.      When a key press is detected, an internal timer is reset to
  1272.      ZERO, and any remaining commands are executed. The internal
  1273.      timer is used in conjunction with the TIMER token.  This command
  1274.      is useful for synchronizing a series of commands to an external
  1275.      event.  See TIMER below, for an example.
  1276.  
  1277.  
  1278.   [module command] TIMER mm:ss.s
  1279.      This token informs XA to issue a command when the internal timer
  1280.      reaches "mm:ss.s".  The built-in timer is initialized to 0 when
  1281.      XA is invoked, or whenever a key press follows a PAUSE command,
  1282.      or when the token "RESET" is parsed. All subsequent TIMER
  1283.      commands are evaluated from the point at which the internal
  1284.      timer was initialized.  
  1285.  
  1286.      One very useful application of the PAUSE and TIMER commands is
  1287.      to synchronize X10-controlled lighting sequences with
  1288.      pre-recorded  music.  For instance, you could assign each song
  1289.      its own command  file.  Each file would start off with a PAUSE
  1290.      (Registered version may use INPORT) token to intialize the 
  1291.      timer, as well as provide a means to start the music and command
  1292.      chain from a common point.  TIMER statements would specify the
  1293.      exact times that the CP-290 would trigger an X10 command at an
  1294.      appropriate moment in the song.
  1295.  
  1296.  
  1297.         PAUSE                      # Wait for any key press, reset timer
  1298.         A1 ON TIMER 0:10.0          # At 10 seconds, turn on A1
  1299.         A1 DIM 0 TIMER 0:20.5      # At 20.5 seconds, fade light out.
  1300.         
  1301.      In this example, the PAUSE waits for a cue to start the
  1302.      sequence. 10 seconds later, A1 is activated. 20.5 seconds after
  1303.      the cue, A1 is DIMMED to a level 0.
  1304.  
  1305.      XA will automatically anticipate and adjust for any delays that
  1306.      may be caused by the CP-290.  For instance,  the amount of time
  1307.      it takes to turn on a lamp may take as much as 1.4 seconds. Even
  1308.      worse, the CP-290 forces a lamp module to go to the fully BRIGHT
  1309.      state before allowing the module to be dimmed - delaying the
  1310.      actual effect by 6 seconds.  In order to have XA compensate for
  1311.      these delays, you should place an X10 command on the same line
  1312.      just prior to the timer command.  For example, the following
  1313.      line turns the lamp on after 7 seconds. However, XA actually
  1314.      issues the command at 5.6 seconds:
  1315.  
  1316.         A1 ON TIMER 0:7.0 
  1317.  
  1318.      Likewise, to completely dim a module to 0% after 10 seconds, XA
  1319.      will begin issuing the command after approximately 4 seconds
  1320.      have elapsed.
  1321.  
  1322.         A1 DIM 0 TIMER 0:10.0 
  1323.  
  1324.      If no commands are programmed on the same line as the TIMER
  1325.      statement, then a default adjustment of 1.4 seconds will be used
  1326.      for commands that appear later.
  1327.  
  1328.      It is very important that you program the 'minutes' field, even
  1329.      if it is zero. Otherwise, XA will convert the 'seconds' field to
  1330.      minutes, and you'll be waiting a long time. For example, do this:
  1331.   
  1332.         TIMER 0:15.5   <--- Do this
  1333.         TIMER 15.5      <--- NOT this
  1334.  
  1335.  
  1336.   RESET
  1337.      When the RESET token is parsed, the internal timer is preset to 0.
  1338.      The PAUSE token also presets the internal timer to 0, but
  1339.      only after a key has been pressed. This token may be useful when
  1340.      used in conjunction with the "INPORT port" statement. (INPORT
  1341.      can monitor a  bit of a selected port and force a RESET when the
  1342.      bit goes TRUE. INPORT is only available in the "registered"
  1343.      version).
  1344.  
  1345.  
  1346.   {DELAY hh:mm:ss}
  1347.      These tokens allow you wait for the specified number of hours,
  1348.      minutes and seconds to pass before executing the next command. 
  1349.      These delays are relative to the present time and do not work in
  1350.      conjunction with the TIMER or PAUSE tokens.  To wait 5 seconds
  1351.      between commands, use:
  1352.  
  1353.         A1 OFF
  1354.         DELAY 0:0:5
  1355.         A2 ON
  1356.  
  1357.  
  1358.   STOP
  1359.      Normally, XA stops execution when it reaches the end of a
  1360.      command file.  The STOP token forces XA to immediately stop
  1361.      execution. It may be placed anywhere in the command file. See
  1362.      the GOSUB example below for an example.  
  1363.  
  1364.  
  1365.   :LABEL
  1366.      This token identifies a location in your command file that you
  1367.      may GOTO or GOSUB later.  Each label must start with a colon ":"
  1368.      character.  Normally, labels will occupy a line by themselves,
  1369.      however they may appear in a line containing other tokens.
  1370.  
  1371.   
  1372.   :EXIT
  1373.      This special label has been reserved for providing controlled
  1374.      shutdown commands.  This label must begin with the colon ":"
  1375.      character.  Whenever the <ESC> key is pressed, the interpreter
  1376.      will jump to the location where the :EXIT label is located and
  1377.      execute any commands placed after the label. Therefore, the
  1378.      :EXIT label should appear towards the end of the command file. 
  1379.      Note that the :EXIT label is not mandatory.  If <ESC> is pressed
  1380.      and the :EXIT label does not appear in the file, then the
  1381.      interpreter simply aborts the remaining commands.  Examine the
  1382.      use of :EXIT in the next example below.    
  1383.  
  1384.  
  1385.   {GOTO :label}
  1386.      These statements instruct XA to jump to a sequence of commands
  1387.      identified by the ":label" and begin executing them. XA
  1388.      continues executing all remaining statements from that point. 
  1389.      If XA has encountered ":label" previously, it will immediately
  1390.      jump to that location. Otherwise, XA will begin searching for
  1391.      ":label" in the remaining portion of the current file, or within
  1392.      other files that may have been "INCLUDED".
  1393.  
  1394.      NOTE: Earlier versions of XA used the following syntax:
  1395.  
  1396.         GOTO :label times         
  1397.  
  1398.      where "times" acted as a counter.  This method is no longer
  1399.      supported. Use the conditional statements (IF/ELSE -
  1400.      "registered" versions only) instead to control looping.
  1401.   
  1402.      The following code flashes (turns ON and OFF) a module addressed
  1403.      as A1  three times. It uses a variable (see Section - Variables)
  1404.      named "COUNTER" that is incremented and tested every time the
  1405.      loop is executed. When COUNTER reaches 3, the IF portion of the
  1406.      test is no longer true, so XA continues with the rest of the
  1407.      program:
  1408.  
  1409.         COUNTER = 0           # Declare and initialize COUNTER to 0
  1410.         :loop
  1411.         A1 ON
  1412.         A1 OFF
  1413.         COUNTER = COUNTER + 1
  1414.         IF (COUNTER < 3)
  1415.            GOTO :loop
  1416.         ENDIF
  1417.         :EXIT
  1418.         A1 OFF
  1419.  
  1420.      Note the special use of the :EXIT label in the above example. If
  1421.      the user pressed the <ESC> during execution inside the loop, XA
  1422.      would abort the loop and search for the :EXIT label. If found,
  1423.      XA would execute the "A1 OFF" statement ensuring that the module
  1424.      was in a known state. Without :EXIT, XA would abort and possibly
  1425.      leave A1 in  the ON state.
  1426.  
  1427.      By using the LABEL and GOTO constructs, you can produce some
  1428.      pretty sophisticated lighting displays.  One application where
  1429.      this could be put to use is for Christmas lighting.  Consider
  1430.      placing solid color Christmas tree light strands on individual
  1431.      lamp dimmers.  Vary the brightness levels of each strand for an
  1432.      everchanging lighting effect. See the sample file XMAS.CMD for
  1433.      an example.
  1434.  
  1435.  
  1436.   {GOSUB :label}
  1437.   (statements go here...)
  1438.   RETURN
  1439.      These statements instruct XA to jump to a sequence of commands
  1440.      identified by ":label" and begin executing them. XA continues
  1441.      executing all remaining statements until it reaches the "RETURN"
  1442.      token. XA then returns control of the program to the point from
  1443.      which it came. 
  1444.  
  1445.      If XA has encountered ":label" previously, it will immediately
  1446.      jump to that location. Otherwise, XA will begin searching for
  1447.      ":label" in the remaining portion of the current file, or within
  1448.      other files that  may have been "INCLUDED". 
  1449.  
  1450.      Placing a subroutine in a program allows you to repeat a
  1451.      sequence of statements in several places without writing the
  1452.      same statements several times.
  1453.  
  1454.      It is good practice to place subroutines in the beginning of the
  1455.      command file so that searching will be minimized. See the sample
  1456.      "XMAS.CMD" command file for an example. 
  1457.  
  1458.      XA may call subroutines that are present in the current file, or
  1459.      any previously "included" file. You may nest up to 20 subroutine
  1460.      levels.
  1461.  
  1462.      The previous "flash" example (using GOTO's) could be rewritten
  1463.      to use GOSUBS as follows:
  1464.  
  1465.         GOSUB :flash   # Once...
  1466.         GOSUB :flash   # ...Twice
  1467.         GOSUB :flash   #    ...Three times
  1468.         STOP            # Tell XA to stop (prevents running into subroutine)
  1469.  
  1470.         :flash         # Start of subroutine
  1471.          A1 ON
  1472.          A1 OFF
  1473.          RETURN         # Return to original caller
  1474.  
  1475.         :EXIT            # Special shutdown sequence...
  1476.         A1 OFF         # ...Ensure A1 is OFF
  1477.  
  1478.  
  1479.   FAST
  1480.      By default, XA always waits for an acknowledgement message from
  1481.      the CP-290 after sending a direct command. You can avoid this
  1482.      wait and speed up the overall execution of XA by including the
  1483.      token "FAST" in your command:
  1484.   
  1485.         XA "PHONE_IN_USE ON FAST"
  1486.  
  1487.      FAST is best used in single command statements. If you attempt
  1488.      to send multiple direct commands using the FAST token, XA will
  1489.      be forced to wait for the acknowledgement message before issuing
  1490.      the remaining commands. 
  1491.  
  1492.      Some computers may experience problems when XA executes a single
  1493.      statement in a batch file using the FAST token. 
  1494.      
  1495.      
  1496. Communications Tokens
  1497. ─────────────────────────────────────────────────────────────────────
  1498.  
  1499. This group of tokens allow you configure XA for your particular
  1500. computers communications setup. The following table lists the
  1501. "standard" I/O port addresses as well as typical IRQ assignments
  1502. for the first (4) serial ports.  Note the potential IRQ conflict
  1503. that might arise with devices COM1/COM3 and COM2/COM4 because of
  1504. the shared IRQ's.  If you have more than 2 devices attached to
  1505. your computers serial ports, beware of this conflict and resolve
  1506. it by assigning a different IRQ to the offending port.  
  1507.  
  1508.            Comm Port    I/O Address   IRQ Level 
  1509.            ---------   -----------   ---------
  1510.               COM1      3F8H (Hex)       4 
  1511.               COM2      2F8H             3 
  1512.               COM3      3E8H             4 
  1513.               COM4      2E8H             3 
  1514.  
  1515.  
  1516.   COMx
  1517.      This token allows you to specify which comm port the interface
  1518.      is attached to.  This token was intended to be placed in the XA
  1519.      initialization and/or command files.  
  1520.  
  1521.         COM3
  1522.  
  1523.      If your port IO address does not match those in the above table,
  1524.      then use the command line parameter [o=xxx], or the file mode
  1525.      token "IO" (see below) to customize the communication
  1526.      characteristics.
  1527.  
  1528.  
  1529.   {IO x}
  1530.      This option allows you to select a different IO address from the
  1531.      default 3F8H (hex).  If your serial port is setup for 2E8H, then
  1532.      use the following line in your command file:
  1533.   
  1534.         IO 2E8H
  1535.  
  1536.      Notes:
  1537.       * When using HEXADECIMAL numbers, you must specify the H.  This is
  1538.         no longer implied.
  1539.  
  1540.       * These tokens were intended to be placed in the initialization or
  1541.         command files.  
  1542.  
  1543.   {IRQ x}
  1544.      This option allows you to select a different IRQ level from the
  1545.      default interrupt 4.  To use COM3 (an IO address of 3E8) with an
  1546.      IRQ level 5, use the following commands in the XA initialization
  1547.      file:
  1548.  
  1549.         IO 3E8H
  1550.         IRQ 5
  1551.         
  1552.  
  1553. I/O Port Control             ( ** Registered Version Only ** )
  1554. ─────────────────────────────────────────────────────────────────────
  1555.  
  1556. XA can read and write to most of the I/O ports. Of particular
  1557. interest is the Joystick or Game port. This port (location 201
  1558. Hex) provides up to four digital inputs. XA can read the state
  1559. of these ports and react accordingly. See the sample command
  1560. file "JOYSTICK.CMD" for an example of turning a light on or off
  1561. based on the state of the joystick switch settings.
  1562.  
  1563.  
  1564.   {(variable =) INPORT io_port}
  1565.      Read the status of the selected port, and optionally store it
  1566.      into a variable for later processing.  Example: Read the status
  1567.      of the Joystick port (201H) and save it into a variable called
  1568.      "joy_port".
  1569.  
  1570.         joy_port = INPORT 201H
  1571.  
  1572.  
  1573.   {OUTPORT io_port value}
  1574.      Output a byte value to the selected io_port. 
  1575.  
  1576.  
  1577.  
  1578.                     IMPORTANT NOTE:
  1579. When dealing with IO ports, make sure you know what you are
  1580. doing.  Connecting devices that should not be connected to a
  1581. port may cause damage to your computer, its peripherals, even
  1582. you. Be careful that you are writing to the proper ports,
  1583. otherwise you may crash your system.  If you are not sure what
  1584. you are doing, then you better not do it. I will in no way be
  1585. responsible for your use, misuse, or abuse  you might possibly
  1586. inflict on you or your computer.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591. Miscellaneous Tokens 
  1592. ─────────────────────────────────────────────────────────────────────
  1593.  
  1594.   {DEFINE x z}
  1595.      This token is designed to be used in initialization or command
  1596.      files.  It allows you to substitute several tokens into a single
  1597.      token of your choice. It will help to make command files more
  1598.      readable.  For example, you can assign the token:
  1599.  
  1600.         "XMAS_ON" 
  1601.  
  1602.      to an equivalent group of tokens, such as:
  1603.  
  1604.         "HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY" 
  1605.  
  1606.      as follows:
  1607.  
  1608.         DEFINE   XMAS_ON   HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY
  1609.                  <--x-->   <----------------- z ----------------->
  1610.  
  1611.      Notice that the "x" portion uses underscore characters "_" to 
  1612.      separate the words but to keep the string contiguous.  This is
  1613.      important because the XA interpreter looks for the first SPACE
  1614.      character to separate the "x" and "z" components.  All
  1615.      subsequent SPACE characters are ignored.
  1616.   
  1617.      Later in the command file, you can use the following command to
  1618.      activate your Christmas lights:
  1619.  
  1620.         XMAS_ON
  1621.  
  1622.      Internally, XA will convert this string to its equivalent:
  1623.  
  1624.         HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY
  1625.  
  1626.      More Examples:
  1627.  
  1628.                  :
  1629.         DEFINE PLANT_GROW_LIGHTS A8
  1630.         DEFINE OUTSIDE_LIGHTS A1
  1631.         DEFINE ALL_ON ALL_LIGHTS_ON HOUSE A ON
  1632.                  :
  1633.         PLANT_GROW_LIGHTS ON TIME 6:00 AM EVERYDAY 
  1634.         PLANT_GROW_LIGHTS OFF TIME 12:00 AM EVERYDAY
  1635.                  :
  1636.         OUTSIDE_LIGHTS OFF SUNRISE EVERYDAY
  1637.                  :
  1638.         ALL_ON SUNDAY TIME 7:30 PM
  1639.  
  1640.      The use of DEFINES is helpful if you want to monitor the CP-290
  1641.      for events as they occur.  See Section - Monitoring.  
  1642.  
  1643.  
  1644.   {EVENT xxx}
  1645.      The CP-290 can store up to 128 events in its memory.  Each event
  1646.      occupies fixed locations in memory.  Prior to XA Version 2.0 you
  1647.      were required to assign a unique event number if you did not
  1648.      want to overwrite an existing event.  Since XA now automatically
  1649.      determines the next available slot for you, there is little need
  1650.      for these tokens.  However, these tokens remain as part of XA
  1651.      should you need to overwrite a particular event.
  1652.  
  1653.      When you produce a report file, the event number assigned to
  1654.      each event is printed in the right-most column of the  listing. 
  1655.      If you produced a report file while using the "-e" (no command
  1656.      execution), then the event number displayed will be -1,
  1657.      signifying that the event is not stored in the CP-290.  
  1658.  
  1659.  
  1660.   {CLEAR EVENT xxx}
  1661.      These tokens delete the specified event from the computer
  1662.      interface.  See description for EVENT xxx above. Only 1 event
  1663.      may be cleared per command.
  1664.  
  1665.         XA "CLEAR EVENT 100" "CLEAR EVENT 101" 
  1666.  
  1667.      When an event is cleared from the interface, the actual memory
  1668.      locations it occupied are cleared to zero.  All subsequent
  1669.      events remain in their assigned memory locations.  Use the
  1670.      report listing to display each events number (or location) in
  1671.      the CP-290. This number is printed in the right-most column of
  1672.      the report.  Any event numbers that are followed by an asterisk
  1673.      "*" indicate that the event  will be  triggered on multiple
  1674.      days.  
  1675.  
  1676.  
  1677.   ERASE
  1678.      This token erases all events from the CP-290 memory. If you use
  1679.      XA to maintain you CP-290 schedules, then this token should
  1680.      appear at the beginning of the command file. This is important
  1681.      because XA tries to append new events to the existing events in
  1682.      the CP-290.  If you do not erase the CP-290 memory, you will
  1683.      exceed its 128 event capacity.
  1684.  
  1685.      Always use this token when specific dates (declared by the
  1686.      DATE/THRU tokens) are present in your command file.  This way,
  1687.      once the date has come and gone, it will be deleted from the
  1688.      CP-290 memory automatically.
  1689.  
  1690.  
  1691.   {BASECODE x}
  1692.      These tokens change the base housecode of the interface WITHOUT 
  1693.      losing the data stored in the interface. Prior to changing the 
  1694.      housecode, a complete upload of all events stored in the
  1695.      interface is  performed.  The housecode is changed, then all
  1696.      events are downloaded  back into the interface.  Valid
  1697.      housecodes are A...P.
  1698.  
  1699.         XA "BASECODE D"
  1700.  
  1701.      XA displays a bar graph during the upload and download phases
  1702.      providing a visual indication of progress, as well as the amount
  1703.      of available event storage.
  1704.  
  1705.  
  1706.   DIAGNOSE
  1707.      This token triggers the CP-290's built-in diagnostic routine. 
  1708.      You will be informed of the results after a few seconds.  Since
  1709.      the diagnostics overwrite any existing events, XA first uploads
  1710.      the contents of the CP-290 memory prior to the diagnostic.  If
  1711.      the diagnostics report an OK status, then the events are
  1712.      downloaded back to the CP-290.  
  1713.  
  1714.   
  1715.   {XACMD filename}
  1716.      This token is intended to be placed inside the XA initialization
  1717.      file (XA.INI - see next section).  It defines the default
  1718.      command file that XA should parse and execute if no other
  1719.      commands files or direct commands are present.  If your XA.INI
  1720.      file contains the following  line:
  1721.  
  1722.         XACMD EVENTS.CMD
  1723.  
  1724.      Then each time XA is invoked without any arguments, the file
  1725.      "EVENTS.CMD" will be parsed and executed.  
  1726.  
  1727.      The following examples show how you can specify unique command
  1728.      files based on the day of the week (see later section for
  1729.      IF/ELSE programming):
  1730.  
  1731.         IF ((CDAY == MON) OR (CDAY == WED) OR (CDAY == FRI))
  1732.            XACMD M_W_F.CMD
  1733.         ELSE
  1734.            XACMD XA.CMD
  1735.         ENDIF
  1736.  
  1737.  
  1738.   {INCLUDE filename}
  1739.      These tokens allow XA to parse additional files.  When XA reads
  1740.      the "INCLUDE filename" statement, it begins to parse the
  1741.      requested file.  Upon reaching the end of the new file, XA will
  1742.      begin parsing the original file at the statement following the
  1743.      INCLUDE.  This concept  is similar to calling and returning from
  1744.      a subroutine. 
  1745.  
  1746.      The include file may be called from your XA.INI as well as
  1747.      XA.CMD (or any other file). Include files may be nested up to 20
  1748.      levels deep.  The following example shows you how XA.CMD could
  1749.      include VACATION.CMD if the current date (CDATE) falls between
  1750.      AUG 21 and AUG 28.
  1751.  
  1752.         IF ((CDATE >= DATE 8/21) AND (CDATE <= DATE 8/28))
  1753.            INCLUDE VACATION.CMD
  1754.         ENDIF
  1755.  
  1756.  
  1757.   {DOS command_string}
  1758.      The DOS token allows you to execute any DOS command from within
  1759.      XA.  The following line (taken from JOYSTICK.CMD) tells the
  1760.      SoundBlaster to play the GREETING.VOC file:
  1761.  
  1762.         DOS c:\sblaster\vplay c:\sblaster\greeting.voc
  1763.  
  1764.      Display a directory:
  1765.         
  1766.         DOS dir
  1767.  
  1768.      Use XA to kickoff a communications program at a precise time
  1769.      (see PHONE.CMD):
  1770.  
  1771.         # At 11:15, Call BBS...        
  1772.         DISPLAY OFF        
  1773.         :WAIT        
  1774.         IF (CTIME < TIME 11:15 PM)          
  1775.            GOTO :WAIT        
  1776.         ENDIF        
  1777.  
  1778.         DOS PROCOMM options...     # Invoke PROCOMM with command line    
  1779.                                    # parameters...
  1780.  
  1781.         
  1782.   BEEP
  1783.      The BEEP token will issue a short tone through your PC's speaker.
  1784.  
  1785.  
  1786.   {DISPLAY ON}
  1787.   {DISPLAY OFF}
  1788.      XA will display just about every statement as its parsed. There
  1789.      may be instances where you don't want the display active, for
  1790.      instance, parsing the XA.INI file, comments, or when critical
  1791.      loops are being  processed. XA allows you to control the display
  1792.      with the commands:
  1793.  
  1794.         DISPLAY ON              
  1795.         DISPLAY OFF
  1796.  
  1797.      In some instances, it will be necessary to turn the command
  1798.      display off because of time considerations. If you are in a
  1799.      tight loop monitoring an IO port for a bit to change, you may
  1800.      miss the toggle while XA is printing the current statement to
  1801.      the CRT. By turning the display off, you allow XA to execute
  1802.      much faster, virtually eliminating any bottlenecks that may
  1803.      cause XA to miss an event from the port.
  1804.  
  1805.      The sample XA.INI file shipped with this version has the display
  1806.      turned off at the start of the file, and restores the display at
  1807.      the  end of the file.
  1808.  
  1809.  
  1810. Reporting Tokens 
  1811. ─────────────────────────────────────────────────────────────────────
  1812.  
  1813.   MONITOR
  1814.      This token informs XA to continuously monitor the communications
  1815.      port for any messages sent by the CP-290 when it executes a
  1816.      stored event or when one of the panel buttons is pressed.  See
  1817.      section -  "Monitoring and Logging Events" for more information.
  1818.  
  1819.  
  1820.   LOG
  1821.      This token appends the monitored information in the file XA.LOG. 
  1822.  
  1823.  
  1824.   REPORT1
  1825.      This token will produce a report file with events sorted by day
  1826.      and time.
  1827.  
  1828.  
  1829.   REPORT2
  1830.      This token will produce a report file with events sorted by day,
  1831.      module, and time.
  1832.  
  1833.  
  1834.  
  1835. Powerfail Recovery 
  1836. ─────────────────────────────────────────────────────────────────────
  1837.  
  1838. Powerfail recovery allows you to restore each module to its
  1839. scheduled state. By default, XA uses the last 6 days to
  1840. determine the state.  You can tell XA to use additional days if
  1841. necessary.  Also, you can tell XA to FORCE a module to a
  1842. particular state overriding the calculated state, or have XA
  1843. IGNORE the calculated state and not send any command to the
  1844. module.
  1845.  
  1846. Powerfail recovery may be invoked from the command line using
  1847. the following parameters:
  1848.  
  1849.   +P   - parses command file, then performs recovery.
  1850.  
  1851.   -P   - immediate recovery, no parsing of command file.
  1852.  
  1853. If you want XA to review the event schedule of the previous 4
  1854. days in order to determine the correct state, then append a 4 to
  1855. the command, for example -P4 or +P4.  The maximum number of days
  1856. that XA can scan is 6.  XA uses the information stored in the
  1857. file X10.DAT for the schedule calculations because it's faster
  1858. than uploading all the data from the CP-290.  Also, if you
  1859. change your schedule with X10's original software package
  1860. (X10.EXE), those changes will be reflected properly.  If XA can
  1861. not find the X10.DAT, then XA will upload the data from the
  1862. CP-290.  
  1863.  
  1864. There are two token statements which can override powerfail's
  1865. determined module state. These overrides may be used for certain
  1866. modules that do not have any programmed events stored in the
  1867. CP-290.
  1868.  
  1869.  
  1870.   {FORCE module state}
  1871.      Forces a module to a desired state, no matter what powerfail
  1872.      recovery  thinks it should be in. "Module"  can be a module
  1873.      address (A1) or pre-defined name (STAIRS). "State" can be any of
  1874.      the following X10 commands: 
  1875.  
  1876.         ON, OFF, DIM %%
  1877.  
  1878.      Example:
  1879.  
  1880.         FORCE P_C ON
  1881.  
  1882.  
  1883.   {IGNORE module}
  1884.      Ignores sending any command to module during a powerfail
  1885.      recovery. "Module" can be a module address or pre-defined name.
  1886.  
  1887.      Example:
  1888.  
  1889.         IGNORE DEHUMIDIFIER
  1890.  
  1891.  
  1892.      Use the command line option "-e" in conjunction with powerfail
  1893.      recovery to see how XA would have restored each module without
  1894.      sending any X10 commands:
  1895.      
  1896.         XA -e -p
  1897.  
  1898.         
  1899. Screen Color Control           ( ** Registered Version Only ** ) 
  1900. ─────────────────────────────────────────────────────────────────────
  1901.  
  1902. Screen color control lets you program how commands should be
  1903. displayed.  You will be able to tell at a glance how certain
  1904. conditional statements (IF/ELSE) were evaluated by XA just by
  1905. looking at the display.
  1906.  
  1907.   {VIDEO1 Foreground Background}
  1908.      IF or ELSE evaluates to TRUE  
  1909.  
  1910.   {VIDEO2 Foreground Background}
  1911.      IF or ELSE evaluates to FALSE
  1912.  
  1913.   {VIDEO3 Foreground Background}
  1914.      Sending DIRECT commands to CP-290
  1915.  
  1916.   {VIDEO4 Foreground Background}
  1917.      Sending EVENTS to CP-290
  1918.  
  1919.      FOREGROUND may be any of the following:
  1920.         BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
  1921.         DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
  1922.         LIGHTMAGENTA, YELLOW, WHITE
  1923.  
  1924.      BACKGROUND may be any of the following:
  1925.         BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY
  1926.  
  1927.      To display a "TRUE" IF/ELSE statement in GREEN foreground
  1928.      characters on a BLACK background, and  a "FALSE" IF/ELSE
  1929.      statement in RED foreground characters on a BLACK background:
  1930.  
  1931.         VIDEO1 GREEN BLACK
  1932.         VIDEO2 RED BLACK
  1933.  
  1934.      To display a DIRECT command (XA "P1 ON") in YELLOW on BLACK:
  1935.      
  1936.         VIDEO3 YELLOW BLACK
  1937.  
  1938. ═════════════════════════════════════════════════════════════════════
  1939. 10.  Programming Additions          ( ** Registered Version Only ** )
  1940. ═════════════════════════════════════════════════════════════════════
  1941.  
  1942. Variables
  1943. ─────────────────────────────────────────────────────────────────────
  1944.  
  1945. Variables are user-defined objects which may be assigned values,
  1946. or examined. You can assign numbers, dates, times, port data,
  1947. true/false data into a variable. 
  1948.  
  1949. Variables are dynamically created at the first instance when XA
  1950. parses a token that is not part of the normal XA language. For
  1951. instance, the following statement declares a variable called
  1952. VACATION, because VACATION is not part of XA's syntax.
  1953.  
  1954.      vacation = WEEKEND
  1955.  
  1956. Internally, variables are treated as 32 bit integer values. When
  1957. variables are created they are initialized to 0 as soon as they
  1958. are parsed. However, they may be assigned a different value in
  1959. the declaring statement. In the above example, "VACATION" was
  1960. assigned the value WEEKEND (the internal value is set to 96, or
  1961. 60 Hex - but you  don't really need to know that).  
  1962.  
  1963. The next example declares a variable called "ATHOME", assigning
  1964. it a value of 1.
  1965.  
  1966.      DEFINE TRUE    1
  1967.      DEFINE FALSE   0        
  1968.      ATHOME = TRUE
  1969.  
  1970. First, we define constants TRUE and FALSE to be 1 and 0
  1971. respectively.  Next, we declare a variable called ATHOME.
  1972. Internally, the variable is created and initialized to 0. The
  1973. statement is parsed further, the assignment operator "=" sets
  1974. ATHOME equal to TRUE (or 1).
  1975.  
  1976. When declaring variable, the first character in its name should
  1977. begin with an ALPHA character, that is, A...Z. You can then use
  1978. numbers as part of the name, but they must not start the name.
  1979. All characters are  converted to UPPERCASE.  The list of legal
  1980. characters are:
  1981.  
  1982.      ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_
  1983.  
  1984.  
  1985.  
  1986. Examples:
  1987.  
  1988.      BIRTHDAY    <--- This is OK!
  1989.      1_BIRTHDAY  <--- Can't start with a numeric value        
  1990.      BIRTH,DAY   <--- Comma not a valid character
  1991.  
  1992.      
  1993. Hexadecimal Notation
  1994. ─────────────────────────────────────────────────────────────────────
  1995.  
  1996. Hexadecimal notation specifies an integer value in base 16 or
  1997. "hex" (hexadecimal).  When writing computer programs, it is
  1998. sometimes easier  to work in this base than the normal base 10.
  1999. A hex value has 3  parts:
  2000.  
  2001.   0 NNNNNNN H
  2002.  
  2003.   where:
  2004.      0 - A leading zero is required if the first digit of the hex 
  2005.         number is an alphabetic character (A...F) so that XA can
  2006.         distinguish it as a number and not a variable name. A leading
  2007.         zero may also be used in front of a numeric character in the hex
  2008.         number just as in a normal integer constant (0987H = 987H).
  2009.  
  2010.      NNNNNNN - The eight Ns represent the 8 hexadeciaml digits in the
  2011.         range of 0...F.
  2012.  
  2013.      The trailing H indicates the number is hex and is always
  2014.      required.
  2015.  
  2016.   Example:
  2017.  
  2018.      IO 3E8H
  2019.  
  2020.  
  2021. Note: previous versions of XA assumed hex numbers for certain
  2022. tokens (such as IO). This is no longer the case! 
  2023.  
  2024.  
  2025. Pre-Defined Variables:
  2026. ─────────────────────────────────────────────────────────────────────
  2027.  
  2028. XA maintains several built-in variables that are accessible by
  2029. your programs. These variables are:
  2030.  
  2031.   CDATE
  2032.      The current date (month-day-year).
  2033.  
  2034.      Internally, XA maintains the current date as a 32 bit long
  2035.      integer. CDATE is actually the number of days since 1/1/1970. 
  2036.      You can perform simple math and logical operations to this
  2037.      variable to test for special conditions. For instance, to run a
  2038.      special command file called XMAS.CMD between Thanksgiving and
  2039.      New Years Eve:
  2040.  
  2041.         IF ((CDATE >= DATE 11/25) AND (CDATE <= DATE 12/31))
  2042.            INCLUDE XMAS.CMD
  2043.         ENDIF
  2044.  
  2045.  
  2046.      When comparing dates with CDATE, make sure you specify the DATE
  2047.      token:
  2048.  
  2049.         IF (CDATE == 12/25)      <--- This is WRONG!
  2050.         IF (CDATE == DATE 12/25)   <--- This is CORRECT!
  2051.  
  2052.  
  2053.  
  2054.   CDAY
  2055.      The current day of the week (MON, TUE, WED...)
  2056.  
  2057.      Internally, XA maintains the current day as an X10 bit-pattern,
  2058.      that is MON = 1, TUE = 2, WED = 4, ...SUN = 40Hex. The Day
  2059.      Tokens (MON, TUE... SUN) are also mapped to these values, so you
  2060.      can use them in conjunction with logical operations when
  2061.      determining special days. The file XMAS.CMD performs a test on
  2062.      CDAY to see if its FRI or SAT, thus allowing the Christmas
  2063.      lights to stay on longer:
  2064.  
  2065.         IF ((CDAY == FRI) OR (CDAY == SAT))
  2066.            IF (CTIME >= TIME 11:30 PM)
  2067.               GOTO EXIT
  2068.            ENDIF
  2069.         ELSE
  2070.            IF (CTIME >= TIME 10:30 PM)
  2071.               GOTO EXIT
  2072.            ENDIF
  2073.         ENDIF
  2074.         GOTO LOOP         # It's not time yet, repeat the loop.
  2075.  
  2076.  
  2077.   CTIME
  2078.      The current time (in 24-hour format)
  2079.  
  2080.      Internally, XA maintains the current time as the number of
  2081.      seconds since midnight.  You can perform arithmetic and logical
  2082.      operations on this variable by using the TIME token. See the
  2083.      previous example for a way of leaving Christmas lights on until
  2084.      11:30 pm on FRI and SAT nights, all other nights they are
  2085.      shutdown at 10:30 pm.
  2086.      
  2087.      
  2088. Operators
  2089. ─────────────────────────────────────────────────────────────────────
  2090.      
  2091. Operators allow some kind of operation to be performed to
  2092. variables and constants. Operators are evaluated as they are
  2093. parsed from left to right.  When an expression is contained in
  2094. parentheses, that expression will be evaluated first. When
  2095. nested parentheses are present, the inner most expression is
  2096. evaluated, then the one immediately outside of it, and so on.
  2097.  
  2098. Arithmetic Operators
  2099. ─────────────────────────────────────────────────────────────────────
  2100.  
  2101.      Operator    Function    Example 
  2102.      ========    ========    =========
  2103.         *        Multiply    A = B * C 
  2104.         /        Divide      B = A / C 
  2105.         +        Addition    C = A + B 
  2106.         -        Subtraction A = C - B 
  2107.         -        Unary Minus A = -B 
  2108.  
  2109.  
  2110. Relational Operators
  2111. ─────────────────────────────────────────────────────────────────────
  2112.  
  2113.      Operator    Function 
  2114.      ========    =============================
  2115.         =        Assigns a value to a variable 
  2116.         <        Less than 
  2117.         >        Greater than 
  2118.         <=       Less than or equal 
  2119.         >=       Greater than or equal 
  2120.         <>       Not equal  
  2121.         ==       Equals (values match) 
  2122.  
  2123.  
  2124. Logical Operators
  2125. ─────────────────────────────────────────────────────────────────────
  2126.  
  2127. Produce either a FALSE (0) or TRUE (1) result
  2128.  
  2129.      Operator    Function 
  2130.      ========    =============================
  2131.         AND      Logical AND 
  2132.         &&       Logical AND (same as AND) 
  2133.         OR       Logical OR 
  2134.         ||       Logical OR (same as OR) 
  2135.         !        NOT 
  2136.  
  2137.  
  2138. Truth Table for logical operators
  2139. ─────────────────────────────────────────────────────────────────────
  2140.  
  2141.         A    B   A AND B   A OR B    ! A 
  2142.        ===  ===  =======  =======    ===
  2143.         0    0      0        0        1 
  2144.         0    1      0        1        1 
  2145.         1    0      0        1        0 
  2146.         1    1      1        1        0 
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152. Bitwise Logical Operators                
  2153. ─────────────────────────────────────────────────────────────────────
  2154.  
  2155. These operators are used to mask off some set of bits (AND), or
  2156. to turn on some bits (OR). You will need these when using XA in
  2157. conjunction with IO ports.
  2158.  
  2159.      Operator    Function 
  2160.      ========    =============================
  2161.         |        Bitwise OR 
  2162.         &        Bitwise AND 
  2163.  
  2164.  
  2165. IF/ELSE/ENDIF Statements
  2166. ─────────────────────────────────────────────────────────────────────
  2167.  
  2168. The IF/ELSE/ENDIF statement provides a transfer of control based
  2169. on the result of a relational or comparison expression. The
  2170. IF/ELSE/ENDIF statement has the following format:
  2171.  
  2172.   IF (expression)
  2173.      statements
  2174.   [ ELSE
  2175.      statements ]
  2176.   ENDIF
  2177.  
  2178.  
  2179. The expression within parentheses is evaluated. If the
  2180. expression evaluates to TRUE, then the series of statements
  2181. starting on the next line are executed. If the expression
  2182. evaluates to FALSE, and there is an ELSE clause, then the series
  2183. of statements on the lines following the ELSE will be executed. 
  2184. The ELSE clause is optional. If there is no ELSE clause, then
  2185. execution continues immediately following the ENDIF statement.
  2186.  
  2187. Conditional IF/ELSE/ENDIF statements may be nested up to 100
  2188. levels deep.
  2189.  
  2190.   IF (1 < 2)
  2191.      IF (2 < 3)
  2192.         IF (3 < 4)
  2193.            A = 5
  2194.         ENDIF
  2195.      ENDIF
  2196.   ENDIF
  2197.  
  2198. Each conditional expression must finish with an ENDIF clause so
  2199. the parser can evaluate further statements.
  2200.  
  2201. Indentation is used throughout these examples and you are urged
  2202. to indent your programs too. Proper indentation makes your
  2203. program much easier to read.  Complex conditional statements may
  2204. be evaluated. The above example could be rewritten as:
  2205.  
  2206.   IF ((1 < 2) AND (2 < 3) AND (3 < 4))
  2207.      A = 5
  2208.   ENDIF
  2209.  
  2210. Use parentheses () to group individual expressions. Grouping
  2211. ensures that expressions are evaluated correctly, as well as
  2212. makes your program more readable.
  2213.  
  2214.  
  2215. ═════════════════════════════════════════════════════════════════════
  2216. 11.  XA.INI - Initialization file 
  2217. ═════════════════════════════════════════════════════════════════════
  2218.  
  2219. XA supports the use of an initialization file called XA.INI. 
  2220. This file is intended to hold tokens and communication
  2221. parameters that you use regularly.  For instance, the following
  2222. tokens are ideal candidates for inclusion in the initialization
  2223. file:
  2224.  
  2225.   COMx           - Communication port
  2226.   IO x           - Special IO port address
  2227.   IRQ x          - Special IRQ level 
  2228.   DEFINE x y     - Place as many DEFINE statements as you want 
  2229.   LATITUDE dms   - The latitude of your city
  2230.   LONGITUDE dms  - The longitude of your city
  2231.   TIMEZONE x     - Your timezone
  2232.   DST            - If Daylight Savings is observed
  2233.   XACMD file     - The command file to use as a default
  2234.  
  2235. This file, always called XA.INI, is the very first file that the
  2236. XA parser looks for.  If it is found in the current directory
  2237. (or the directory specified by the XA environment variable - see
  2238. Installation) then the file is scanned for all tokens described
  2239. above. These tokens are then used to define modules or override
  2240. default communication parameters.
  2241.  
  2242. The following example is taken from the file XA.INI distributed
  2243. with this software.
  2244.  
  2245.      DEFINE P_C C1
  2246.      DEFINE DEN A5
  2247.      DEFINE GARAGE A1
  2248.         :
  2249.      LATITUDE 41°35'
  2250.      LONGITUDE 81°20'
  2251.      TIMEZONE 5 DST
  2252.         :
  2253.      COM3
  2254.      IRQ 5
  2255.      
  2256. Since XA.INI is always parsed, this allows you to send
  2257. descriptive X10 commands that don't rely on your memory for the
  2258. actual house and unit codes.  For instance:
  2259.  
  2260.      XA "DEN ON"
  2261.  
  2262. turns ON the unit at Housecode A Unit 5.
  2263.  
  2264. Do not place events or direct commands in this file, or they
  2265. will be executed every time you invoke XA.  XA is only looking
  2266. for tokens that describe your particular setup.  Events and
  2267. direct commands should be placed in command files (see next
  2268. section).
  2269.  
  2270. You may place comments in your initialization file.  A comment
  2271. is delineated by the pound sign character "#".  The comment
  2272. symbol may appear in any column. Once XA sees the comment, the
  2273. rest of the line is ignored.  Therefore, comments can be placed
  2274. in front of tokens you do not want to be parsed by the
  2275. interpreter at this time
  2276.  
  2277.      # This is an example comment. Place them after statements too:
  2278.      LATITUDE  41°35'          # Latitude of Mentor, OH.
  2279.  
  2280. When creating this file, use an editor or word processor that
  2281. stores its files in pure ascii format.  Otherwise the formatting
  2282. characters that the word processor embeds within the file will
  2283. confuse the XA parser.
  2284.  
  2285. The token XACMD specifies the default command file that should
  2286. be executed if no direct command was included at the DOS prompt.
  2287.  The next section describes what command files are and how they
  2288. are used with XA.
  2289.  
  2290.  
  2291.  
  2292. ═════════════════════════════════════════════════════════════════════
  2293. 12.  Command Files
  2294. ═════════════════════════════════════════════════════════════════════
  2295.  
  2296. Since the CP-290 is only capable of storing a single weeks worth
  2297. of events, command files were created to allow easy updates of
  2298. the events that may need to be revised due to ever-changing
  2299. conditions such as sunrise and sunset times.  Also, specific
  2300. date information may be contained within this file.  XA has the
  2301. capability to interpret these dates and update the CP-290
  2302. accordingly. See the sample command  file "XA.CMD" (included in
  2303. this package) I use for automating events  in my home.    
  2304.  
  2305. Command files work very well for executing a series of direct
  2306. commands too. See the sample file XMAS.CMD for an example of an
  2307. X10 lighting script.
  2308.  
  2309. Command files should only be created with an editor or word
  2310. processor  that saves files in pure ASCII format.  Any
  2311. extraneous characters or control codes will cause the XA
  2312. interpreter to ignore your commands.  XA defaults to reading a
  2313. command file if there are no commands in the command line and as
  2314. long as the statement  "XACMD filename" was included in your
  2315. XA.INI file. You may override the default command file by using
  2316. the "f=filename" option when starting XA.  For example, if you
  2317. wanted to execute the commands found in a file called
  2318. 'MONITOR.CMD', you would start the XA utility as:
  2319.  
  2320.      XA f=MONITOR.CMD
  2321.  
  2322. Prior to Version 2.0, XA would only execute either command files
  2323. or commands passed as arguments to XA on the DOS command line -
  2324. NOT  BOTH.  With version 2.0, you can execute both types at the
  2325. same time, however the file must be specified using the
  2326. "f=filename" syntax.  This is very useful when you want to pass
  2327. a variable to a command file (Registered version only). For
  2328. example, suppose your normal command file (XA.CMD) contains
  2329. special lighting events that you activate when you plan on
  2330. vacationing for the weekend:
  2331.  
  2332.   XA.CMD:
  2333.      # Normal Events...
  2334.      GARAGE ON SUNSET WEEKDAYS
  2335.         ...
  2336.      # Special Vacation Events...
  2337.      if (vacation)
  2338.         HALLWAY ON TIME 9:30 PM WEEKENDS SECURITY
  2339.         HALLWAY OFF TIME 11:30 WEEKENDS RANDOM 10
  2340.         STEREO ON TIME 3:30 PM WEEKENDS RANDOM 15
  2341.         STEREO OFF TIME 11:15 PM WEEKENDS RANDOM 5
  2342.      endif
  2343.  
  2344.  
  2345. To activate the vacation sequence, you must specify both XA.CMD
  2346. and set the vacation variable to TRUE:
  2347.  
  2348.      XA f=XA.CMD "VACATION = 1"
  2349.  
  2350.  
  2351. ═════════════════════════════════════════════════════════════════════
  2352. 13.  Initialization file, Command files, and Command Line Options
  2353. ═════════════════════════════════════════════════════════════════════
  2354.  
  2355. This section tries to clear any confusion you may have about the
  2356. initialization file, command files, and command line options.
  2357. Each serves a unique purpose, offering a very easy and flexible
  2358. means of  controlling your X10 equipment.  As discussed earlier,
  2359. XA provides the mechanism for controlling the CP-290 via the DOS
  2360. prompt (including batch files) or from a text-based file.  XA
  2361. distinguishes which mode of operation it takes by examining the
  2362. way you invoked XA.  If any direct (or immediate) commands are
  2363. present, then XA sends the command directly to the CP-290.  For
  2364. instance, the following is a direct command:
  2365.  
  2366.      XA "A5 ON"
  2367.  
  2368. It's nicer to assign a meaningful name to your modules, so XA
  2369. allows you to place these names in an initialization file called
  2370. "XA.INI".  You define a module using the following token syntax:
  2371.  
  2372.      DEFINE DEN A5
  2373.  
  2374. Now you can activate the same module using a descriptive (and
  2375. easier  to remember) name:
  2376.  
  2377.      XA "DEN ON"
  2378.  
  2379. Other items may also appear in the intialization file.  If your
  2380. computer communicates with the CP-290 via COM3 serial port, then
  2381. you may place the token "COM3" within the XA.INI too.  XA always
  2382. looks at  this file before attempting any communication with the
  2383. CP-290.  Other tokens that XA looks for are:
  2384.  
  2385.      IRQ, IO, LATITUDE, LONGITUDE, TIMEZONE, DST, XACMD, DEFINE, COMx
  2386.  
  2387. After parsing the XA.INI file, XA then looks to see if the
  2388. "f=filename" option was specified on the command line. This
  2389. allows you to override the default command file you may have
  2390. specified by using the XACMD token in the XA.INI file.  Next,
  2391. the command line options are scanned. Any options defined here
  2392. will override all previous options declared by the
  2393. initialization file.  If a file and a series of commands are
  2394. placed in the XA command line, then XA will execute the command
  2395. and the file.  This allows you to set variables to a specific
  2396. value and later evaluated so special actions can be taken inside
  2397. your command file. See the previous section for more details.
  2398.  
  2399.  
  2400. ═════════════════════════════════════════════════════════════════════
  2401. 14.  Report Files 
  2402. ═════════════════════════════════════════════════════════════════════
  2403.  
  2404. XA can produce a report of all events that were just parsed by
  2405. the interpreter.  These reports come in 2 styles:
  2406.  
  2407.   * Events sorted by day and time
  2408.  
  2409.   * Events sorted by day, module, and time.
  2410.  
  2411. You have the option of selecting any style, or both styles.  The
  2412. report file will be created after the events have been
  2413. downloaded to the CP-290.  The file is named "XA.RPT", and is
  2414. located in the same drive and directory that your "XA"
  2415. environment variable is set to. 
  2416.  
  2417. Each report file will contain a header containing the XA
  2418. copyright notice, revision number, and the date and time the
  2419. file was created.   Next, the event list will be generated
  2420. starting with today's events.  Each day will have it's own
  2421. heading, and if the LATITUDE, LONGITUDE, and TIMEZONE tokens
  2422. were included in either of the initialization or command files,
  2423. then the sunrise and sunset times for this day will be added to
  2424. the report.  
  2425.  
  2426. The format of the report is self-explanatory, but a few items
  2427. are worth noting. The "Description" column retrieves the module
  2428. definition via the "DEFINE" statement. The DEFINE must include
  2429. both the HOUSE and UNIT tokens when  describing a module.  You
  2430. should not use the short cut method, such as:
  2431.  
  2432.      DEFINE Porch_Lights A 1             <=== will NOT work.
  2433.      DEFINE Porch_Lights HOUSE A UNIT 1  <=== will work.  
  2434.  
  2435. The "Event" column displays the actual location of the event in
  2436. the CP-290's memory.  Event locations range anywhere from 0 to
  2437. 127.  Use  this information if you want to CLEAR an event from
  2438. the CP-290  interface (see EVENT, and CLEAR EVENT).  If you
  2439. specify the '-e' command line option, then the events will not
  2440. be downloaded, and all  event numbers will be set to -1.  An
  2441. asterisk (*) following the event number is a flag to warn you
  2442. that the event is triggered on multiple days.  Therefore, if you
  2443. do CLEAR this event, the event will be deleted for the other
  2444. days as well.
  2445.  
  2446.  
  2447. Report Style 1 - Sort by Day and Time
  2448. ─────────────────────────────────────────────────────────────────────
  2449.  
  2450. Use the REPORT1 token in the command file (or use +r1 on the
  2451. command line) to produce a report file which sorts every event
  2452. by the day it  takes place and the time it occurs.  The
  2453. following is a condensed sample of this style.
  2454.  
  2455.  
  2456.  
  2457.   Saturday - September 25, 1993     Sunrise: 7:15:27  Sunset: 7:18:53
  2458.  
  2459.   Time      Cmd   Mode Module Address/Description    Event
  2460.   ========  ===   ==== ==========================    =====
  2461.   1:30 am   OFF        (A3) BEDROOM_LIGHT            ( 75)
  2462.   5:00 am   ON         (B2) DEHUMIDIFIER             ( 77)*
  2463.   6:45 am   OFF        (A6) STAIRS                   ( 84)* 
  2464.   6:45 am   OFF        (H1) HALLWAY                  ( 81)*
  2465.   9:00 am   OFF        (B2) DEHUMIDIFIER             ( 78)*
  2466.  12:30 pm   OFF        (A8) LIVING_ROOM_LAMP         ( 56)
  2467.  12:30 pm   OFF        (A4) FAMILY_ROOM_LAMP         ( 61)
  2468.   5:00 pm   ON         (B2) DEHUMIDIFIER             ( 79)*
  2469.   6:18 pm   ON         (A4) FAMILY_ROOM_LAMP         ( 72)
  2470.   7:18 pm   DIM        (A9) OUTSIDE_PORCH_LIGHT      ( 66)
  2471.   7:23 pm   ON         (A1) DECK_LIGHTS_1            ( 69)
  2472.   7:48 pm   DIM        (A6) STAIRS                   ( 82)*
  2473.   7:48 pm   DIM        (A1) DECK_LIGHTS_1            ( 70)
  2474.   7:48 pm   ON         (A8) LIVING_ROOM_LAMP         ( 67)
  2475.   8:48 pm   OFF        (A1) DECK_LIGHTS_1            ( 71)
  2476.   9:00 pm   OFF        (B2) DEHUMIDIFIER             ( 80)*
  2477.   9:45 pm   DIM        (H1) HALLWAY                  ( 86)*
  2478.  10:34 pm   ON         (A3) BEDROOM_LIGHT            ( 74)
  2479.  10:43 pm   OFF        (A9) OUTSIDE_PORCH_LIGHT      ( 76)
  2480.  11:00 pm   DIM        (A6) STAIRS                   ( 83)*
  2481.  
  2482.  
  2483. Report Style 2 - Sort by Day, Module, and Time
  2484. ─────────────────────────────────────────────────────────────────────
  2485.  
  2486. Use the REPORT2 token in the command file (or use +r2 on the
  2487. command line) to produce a report file which sorts every event
  2488. by the day it takes place, the module, and the time it occurs.
  2489. The following is a condensed sample of this style.
  2490.  
  2491.  
  2492.   Saturday - September 25, 1993     Sunrise: 7:15:27  Sunset: 7:18:53
  2493.  
  2494.       Module  Time      Function   Mode     Event
  2495.  
  2496.       (A1) DECK_LIGHTS_1
  2497.               7:23 pm     ON                ( 69)
  2498.               7:48 pm     DIM               ( 70)
  2499.               8:48 pm     OFF               ( 71) 
  2500.  
  2501.       (A3) BEDROOM_LIGHT
  2502.               1:30 am     OFF               ( 75)
  2503.              10:30 pm     ON                ( 74)
  2504.  
  2505.       (A4) FAMILY_ROOM_LAMP
  2506.              12:30 pm     OFF               ( 61)
  2507.               6:18 pm     ON                ( 72) 
  2508.  
  2509.       (A6) STAIRS
  2510.               6:48 am     OFF               ( 84)*
  2511.               7:43 pm     DIM               ( 82)*
  2512.              11:00 pm     DIM               ( 83)*
  2513.               
  2514.       (A8) LIVING_ROOM_LAMP
  2515.              12:30 pm     OFF               ( 56)
  2516.               7:48 pm     ON                ( 67)
  2517.  
  2518.       (A9) OUTSIDE_PORCH_LIGHTS
  2519.               7:18 pm     DIM               ( 66)
  2520.              10:31 pm     OFF               ( 76) 
  2521.  
  2522.       (B2) DEHUMIDIFIER
  2523.               5:00 am     ON                ( 77)*
  2524.               9:00 am     OFF               ( 78)*
  2525.               5:00 pm     ON                ( 79)*
  2526.               9:00 pm     OFF               ( 80)*
  2527.  
  2528.       (H1) HALLWAY      
  2529.               6:48 am     OFF               ( 81)*
  2530.               9:45 pm     DIM               ( 86)*
  2531.  
  2532.         
  2533.  
  2534. ═════════════════════════════════════════════════════════════════════
  2535. 15.  Monitoring and Logging events 
  2536. ═════════════════════════════════════════════════════════════════════
  2537.  
  2538. The CP-290 sends a message to your computer after it processes a
  2539. direct command (via XA.EXE or X10.EXE), or after one of its
  2540. eight keys has been pressed, or when it executes an event stored
  2541. in its memory.  Most software packages (including X10.EXE
  2542. shipped with the CP-290) will ignore these messages.  XA allows
  2543. you to monitor as well as log these transmissions if desired.
  2544.  
  2545. XA will enter its monitor mode after all other commands have
  2546. been processed.  You can activate the monitor feature in two
  2547. ways: as a  command, or as a command line parameter.
  2548.  
  2549. Command example:
  2550.  
  2551.      XA "MONITOR"
  2552.  
  2553. Command line parameter example:
  2554.  
  2555.      XA +m -e
  2556.  
  2557. In the first example, XA "MONITOR",  the command "MONITOR"
  2558. informs XA to watch for any transmissions from the CP-290.  The
  2559. second example uses command line options and has the same
  2560. effect, but remember that if no commands were actually present,
  2561. the XA utility will try to open the default command file and
  2562. process the commands found in there.  If you don't want that to
  2563. happen, use the "-e" option which tells XA not to execute (or
  2564. download) those commands.
  2565.  
  2566. When XA begins to monitor, it displays the following message:
  2567.  
  2568.      Monitor events.  Press <ESC> when finished...
  2569.  
  2570. XA then waits for messages from the CP-290.  You may exit this
  2571. function by pressing the <ESC> key.
  2572.  
  2573. When the CP-290 executes an event, it sends a message to the PC
  2574. with the following information; the HOUSE code, UNIT code, and
  2575. the event FUNCTION (ON, OFF, DIM).  XA takes this information
  2576. and adds the time and date information from your PC's clock and
  2577. prints the following  message to the monitor:
  2578.  
  2579.      Sun Mar 24 07:00:13 1991 HOUSE A UNIT 5 ON
  2580.  
  2581. This message is semi-useful; it describes what just occurred but
  2582. if you forgot what was addressed as HOUSE A UNIT 5 then the
  2583. message is meaningless.  You can give this module a more
  2584. descriptive name by using a command file that includes DEFINE
  2585. statements for all your modules.  Below is sample command file
  2586. (MONITOR.CMD - supplied with  this package) that describes what
  2587. we're talking about:
  2588.  
  2589.      DEFINE Porch/Garage_Lights HOUSE A UNIT 1
  2590.      DEFINE Plant_Grow_Lights HOUSE A UNIT 5
  2591.      DEFINE Family_Room_TV HOUSE A UNIT 6
  2592.      DEFINE Basement_Computer HOUSE A UNIT 7
  2593.  
  2594. Now when a message is sent by the CP-290, a scan of all the
  2595. definitions will be made to see if the HOUSE and UNIT codes
  2596. match. If so, then that description will be used instead of the
  2597. codes.  Therefore, you would get the following message on your
  2598. screen:  
  2599.  
  2600.      Sun Mar 24 07:00:13 1991 (A6) Plant_Grow_Lights ON
  2601.      Sun Mar 24 08:43:13 1991 (A1) Porch/Garage_Lights ON
  2602.  
  2603. In the above messages, a combined House and Unit code (A6) is
  2604. automatically provided, you don't have to include it as part of
  2605. the DEFINE token.
  2606.  
  2607. Also, the DEFINE must include both the HOUSE and UNIT tokens
  2608. when describing an object.  You can not use the short cut
  2609. method, such as:
  2610.  
  2611.      DEFINE Porch_Lights A 1             <=== will NOT work.
  2612.      DEFINE Porch_Lights HOUSE A UNIT 1  <=== will work.
  2613.  
  2614. If different modules are controlled by a single event, the
  2615. module which has the lowest UNIT code will be displayed.
  2616. Therefore, if modules C9 and C10 are programmed as a single
  2617. event, only C9 will be displayed.  
  2618.  
  2619. You can also log these events to a file called XA.LOG by
  2620. specifying either the LOG token in a command file or the [+l]
  2621. option on the command line.  Each event reported by the CP-290
  2622. will be displayed on  the screen, and also be appended to the
  2623. file XA.LOG.  By appending the information, all previous events
  2624. will be saved.
  2625.  
  2626.  
  2627.  
  2628. ═════════════════════════════════════════════════════════════════════
  2629. 16.  POWERUP Utility 
  2630. ═════════════════════════════════════════════════════════════════════
  2631.  
  2632. The POWERUP utility is provided in this package to help you
  2633. perform unattended, automatic, event downloads to the CP-290 if
  2634. your computer is controlled by an Appliance module.  POWERUP
  2635. should be placed in your AUTOEXEC.BAT file so it will always be
  2636. executed after your computer boots.  This way, it can decide
  2637. whether or not it's time to perform any updates to your
  2638. interface, and it prevents you from needlessly sending commands
  2639. when you don't need to.
  2640.  
  2641. The POWERUP command has the following form:
  2642.  
  2643.      POWERUP d=day [[d=day]...] [w=1,2,3,4,5] s=hh:mm e=hh:mm
  2644.  
  2645. The command line parameters may appear in any order, and they
  2646. must all be present (except for "w="):
  2647.  
  2648.   d=day
  2649.      This is the text string for the day you want to check for. 
  2650.      Legal strings are:
  2651.  
  2652.         MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, 
  2653.         WEEKDAYS, WEEKDAY, WEEKENDS, WEEKEND, EVERYDAY.
  2654.  
  2655.   [w=week]
  2656.      This optional argument allows you to optionally specify the week
  2657.      of the month you want POWERUP to check for. For instance, to
  2658.      have POWERUP check for the 3rd SUNDAY of the month, specify:
  2659.  
  2660.         POWERUP d=SUNDAY w=3 s=2:55 e=3:05
  2661.  
  2662.      You may not specify multiple weeks, however the default
  2663.      condition (not specifying the w= command) will still check every
  2664.      week.
  2665.  
  2666.   s=hh:mm
  2667.      This is the "window" start time.  Hours must be entered in 24
  2668.      hour format only.
  2669.  
  2670.   e=hh:mm
  2671.      This is the "window" end time.  (24 hr format). For example:
  2672.  
  2673.         POWERUP d=SUNDAY s=2:55 e=3:05
  2674.  
  2675.      If the "day" specified matches the day reported by DOS, and the
  2676.      time reported by DOS falls within the specified "window", then
  2677.      POWERUP will return an ERRORLEVEL of 1, otherwise a 0 is
  2678.      returned. Therefore, by placing the proper batch file commands
  2679.      in AUTOEXEC.BAT, you can now execute a variety of functions at
  2680.      certain times.
  2681.      
  2682.      You may enter multiple 'd=day' parameters.  For instance, to
  2683.      have Powerup check for a window beginning at NOON and lasting
  2684.      until 1:00 pm every MONDAY, WEDNESDAY, and FRIDAY, you would
  2685.      enter:
  2686.      
  2687.         POWERUP d=MONDAY d=WEDNESDAY d=FRIDAY s=12:00 e=13:00
  2688.         if errorlevel == 1 echo It's time!
  2689.  
  2690. If your computer is controlled by an Appliance module, you can
  2691. now automatically download revised event times.  See the sample
  2692. AUTOEXEC.BAT file included in this package.
  2693.  
  2694. ═════════════════════════════════════════════════════════════════════
  2695. 17.  FINDX10.EXE 
  2696. ═════════════════════════════════════════════════════════════════════
  2697.  
  2698. A new utility has been added to help determine the configuration
  2699. of the serial port the CP-290 is connected to. After searching
  2700. all ports in your system, FINDX10 determines the IRQ of the port
  2701. and attempts to communicate with the CP-290. If it finds the
  2702. CP-290, it displays the port setup and prompts you if it is OK
  2703. to save the data in your XA.INI file.  If you select 'Y', the IO
  2704. address and the IRQ level tokens are placed at the end of your
  2705. XA.INI file.
  2706.  
  2707. Because of the wide variety of hardware in use, FINDX10 may not
  2708. be able to locate the CP-290.
  2709.  
  2710.  
  2711. ═════════════════════════════════════════════════════════════════════
  2712. 18.  Other Programs and X10 Information 
  2713. ═════════════════════════════════════════════════════════════════════
  2714.  
  2715. XT - Memory Resident Software for the CP-290
  2716. ─────────────────────────────────────────────────────────────────────
  2717.  
  2718. XA is just one of a series of programs that have been developed
  2719. for the X10 CP-290.  If you received XA on a floppy disk, then
  2720. you should have also received a program called XT, a
  2721. terminate-stay-resident  program (or TSR) that sits silently in
  2722. the background waiting for you to activate it with the proper
  2723. keystroke.  This means you can instantly call it from any
  2724. text-based application.  When activated, it displays a list of
  2725. all modules that you can control with the CP-290.  Each line on
  2726. the list contains a description of the module, its address, and
  2727. its current status.  You select the module you want to control,
  2728. and then choose the action (ON, OFF, DIM).  
  2729.  
  2730. Since XT is resident, it continuously monitors the serial port
  2731. for any communication transmitted by the CP-290 (such as when an
  2732. event is issued or when one of the buttons on the unit is
  2733. pressed).  The  status of each module will always be properly
  2734. reflected in the pop-up menu.  
  2735.  
  2736. XT (version 1.2) now comes with utility package called XTS.EXE. 
  2737. XTS has direct access to XT's database of module states.  Every
  2738. command issued by the CP-290 is captured and stored by XT.  XTS
  2739. can return these module states (via errorlevel statements),
  2740. allowing you to write batch files that react to a module's X10
  2741. status.
  2742.  
  2743. XA (2.0) communicates with XT too.  Whenever XA executes a
  2744. direct command, (or monitors X10 activity), it sends the
  2745. information along to XT so the new state is reflected in the
  2746. XT's database.  
  2747.  
  2748. Another feature of XT is its ability to perform a limited
  2749. "power-fail  recovery".  This function analyzes all events
  2750. stored in the CP-290 and sets each module to its proper state
  2751. based on this information.  This feature can be activated during
  2752. program installation, or whenever the menu is displayed.  
  2753.  
  2754.  
  2755. Other Information
  2756. ─────────────────────────────────────────────────────────────────────
  2757.  
  2758. If you would like further information about the X10 system, then
  2759. contact Steve Mueller of the Silicon Valley Video Group.  Steve
  2760. has put together a paper (currently 60 pages) which covers such 
  2761. topics as:
  2762.  
  2763. X10 transmission theory, undocumented functions of the CP-290,
  2764. debugging spurious failures, modifying X10 devices (local
  2765. dimming), descriptions of the PL-513 and TW-523 modules,  CP-290
  2766. Users and Programming Guides, and manufacturers/retailers of X10
  2767. compatible equipment.
  2768.  
  2769. There is a charge for Steves paper. You may contact Steve via:
  2770.      Steve Mueller
  2771.      Silicon Valley Video Group
  2772.      335 Bodega Way
  2773.      San Jose, CA. 95119-1603
  2774.  
  2775.      or via Prodigy - SJCR28A
  2776.  
  2777.  
  2778.  
  2779. ═════════════════════════════════════════════════════════════════════
  2780. 19.  Acknowledgements 
  2781. ═════════════════════════════════════════════════════════════════════
  2782.  
  2783. I would like to thank the following people for their help in
  2784. making XA a better program. The beta testers - Dave Mabry, Ed
  2785. Christie, David Huras, Nira Johnson.  Also, my thanks to Arnold
  2786. Sprague for proofreading the documentation.  Finally, to all the
  2787. folks who have taken the time to register this program and offer
  2788. suggestions.
  2789.  
  2790. ═════════════════════════════════════════════════════════════════════
  2791. 20.  Warranty, Copyright, and Registration Policy
  2792. ═════════════════════════════════════════════════════════════════════
  2793.  
  2794. Limited Warranty
  2795. ─────────────────────────────────────────────────────────────────────
  2796.  
  2797. THIS PRODUCT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. 
  2798. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE PROGRAM
  2799. IS ASSUMED BY YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU (AND
  2800. NOT THE AUTHOR) ASSUME THE ENTIRE COST OF ALL NECESSARY
  2801. SERVICING, REPAIR OR CORRECTION.  FURTHER, THE AUTHOR DOES NOT
  2802. WARRANT, GUARANTEE, OR MAKE REPRESENTATIONS REGARDING THE USE
  2803. OF, OR THE RESULTS OF THE USE OF THIS PROGRAM IN TERMS OF
  2804. CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS, OR OTHERWISE;
  2805. AND YOU RELY ON THE PROGRAM AND IT'S RESULTS SOLELY AT YOUR OWN
  2806. RISK.  THE AUTHOR CANNOT ACCEPT RESPONSIBILITY FOR SYSTEM
  2807. DAMAGE, LOSS OF PROFIT, OR ANY OTHER SPECIAL, INCIDENTAL, OR
  2808. CONSEQUENTIAL DAMAGE RESULTING FROM THE USE OR INABILITY TO USE
  2809. THIS PRODUCT.
  2810.  
  2811. The author DOES warrant to the original licensee of a REGISTERED
  2812. product that the program disk(s) on which the program is
  2813. recorded be free from defects in materials and workmanship under
  2814. normal use and service for a period of ninety (90) days from the
  2815. date of delivery. The author's entire liability and your
  2816. exclusive remedy shall be replacement of the disk not meeting
  2817. this Limited Warranty.
  2818.  
  2819. Copyright
  2820. ─────────────────────────────────────────────────────────────────────
  2821.  
  2822. The XA software package, its utilities and this document is
  2823. Copyright (C) 1991-1993 by Bruce Christensen. All rights
  2824. reserved. 
  2825.  
  2826. Any specific hardware/software names used in this document are
  2827. trademarks of specific manufacturers.
  2828.  
  2829. Regardless of the method of marketing, XA is not in the public
  2830. domain. It is copyrighted by Bruce Christensen. All rights are
  2831. reserved. Copying, duplicating, selling or otherwise
  2832. distributing the registered version of this product is a
  2833. violation of the Law. However, we grant you the right, in fact
  2834. encourage you to make and distribute as many copies of the
  2835. SHAREWARE version of XA as you wish, using any acceptable medium
  2836. of exchange, with the following provisions:
  2837.  
  2838. Please feel free to distribute this SHAREWARE version as often
  2839. as you like, to any interested parties.
  2840.  
  2841. Please do not distribute this program without all of its
  2842. original related files, addendum files, documentation and this
  2843. notice.
  2844.  
  2845. Please do not alter the program or documentation in any manner.
  2846.  
  2847. DISTRIBUTION of the REGISTERED USER version of the program is in
  2848. violation of license agreements and copyright Law!
  2849.  
  2850.  
  2851.  
  2852. Registration
  2853. ─────────────────────────────────────────────────────────────────────
  2854.  
  2855. If you are still using XA beyond the initial 45-day trial
  2856. period, you must register this software with the author. Please
  2857. use the included registration form (REGISTER.TXT) and send a $29
  2858. registration fee to the address below.  Your registration will
  2859. entitle you to the latest full-featured registered version of
  2860. this program, and a printed copy of this user manual. 
  2861.  
  2862. The registered version of XA and its utilities are licensed for
  2863. individual personal use for an unlimited time.
  2864.  
  2865. This is a "living" program - new features are added from time to
  2866. time.  Your input is the basis for future improvements.  Send
  2867. any comments to the address given below, or you may contact me
  2868. on Prodigy,  America On-line, or Internet. 
  2869.  
  2870.      Bruce Christensen
  2871.      6594 Hudson Avenue
  2872.      Mentor, OH.  44060-4545
  2873.  
  2874.  
  2875.      Prodigy ID:  MHNC39A
  2876.      America On-line: AuggieBen
  2877.      Internet: auggieben@aol.com 
  2878.  
  2879.  
  2880.  
  2881. Future Updates
  2882. ─────────────────────────────────────────────────────────────────────
  2883.  
  2884. Future updates of the shareware version XA can be found on these
  2885. BBS's as they become available. The current version of XA will
  2886. be named "X10XA200.ZIP". The last 3 digits of the filename will
  2887. indicate the revision level (in this case, 2.00).
  2888.  
  2889. Dave Mabry, a sysop of the "Going Down BBS" has offered free
  2890. access to his BBS to anyone interested in X10 - Home Automation.
  2891. You will be granted access once you have completed a short
  2892. questionnaire.  The new user password is currently "DRYSUIT".
  2893. This BBS can be reached at:  1-(313)-576-7882.
  2894.  
  2895. Baran-Harper, a Canadian home automation mail order outfit, also
  2896. runs a very popular BBS. There are many programs for the CP-290
  2897. for PC's, Mac's, and other computers. The Baran Harper BBS is a
  2898. free BBS, their number is: 1-(905)-471-6776, or 1-(905)-471-9574.
  2899.  
  2900. Circuit Cellar Inc. publishes "The Computer Applications
  2901. Journal", and runs occasional articles on X10.  Their BBS number
  2902. is 1-(203)-871-1988.
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909. X-10 is a registered trademark of X-10 (USA) Inc.
  2910.  
  2911. Prodigy is a registered service mark and trademark of Prodigy
  2912.   Services Co.
  2913.  
  2914. America On-line is a registered service mark of Quantum Computer
  2915.   Services, Inc. 
  2916.  
  2917.  
  2918. ═════════════════════════════════════════════════════════════════════
  2919. Appendix A. Tokens - Quick Reference
  2920. ═════════════════════════════════════════════════════════════════════
  2921.  
  2922. Action tokens
  2923. ─────────────────────────────────────────────────────────────────────
  2924.  
  2925.   ON - turns ON the specified modules.
  2926.   OFF - turns OFF the specified modules.
  2927.   {DIM %%} - DIM to a % (percentage) level of brightness.
  2928.   {ALL_UNITS_OFF HOUSE x} - turns OFF all modules on selected
  2929.         HOUSEcode.
  2930.   {ALL_LIGHTS_ON HOUSE x} - turns ON all lamp/wallswitch modules
  2931.         on selected HOUSEcode.  
  2932.  
  2933. Module address tokens
  2934. ─────────────────────────────────────────────────────────────────────
  2935.  
  2936.   A1...P16
  2937.   HOUSE A...P
  2938.   UNIT 1...16
  2939.   UNIT ALL
  2940.  
  2941.   
  2942. Coordinate tokens
  2943. ─────────────────────────────────────────────────────────────────────
  2944.  
  2945.   {LATITUDE dms} - your LATITUDE in Degrees and Minutes
  2946.   {LONGITUDE dms} - your LONGITUDE in Degrees and Minutes
  2947.   {TIMEZONE x} - your TIMEZONE (Standard/Daylight Savings)
  2948.   DST - Automatic Daylight Savings adjustments     
  2949.  
  2950.  
  2951. Clock tokens
  2952. ─────────────────────────────────────────────────────────────────────
  2953.  
  2954.   {SYNCHRONIZE PC (EXACT)} - set PC time based on X10 time
  2955.   {SYNCHRONIZE X10 (EXACT)} - set X10 time based on PC time
  2956.  
  2957.  
  2958. Day tokens
  2959. ─────────────────────────────────────────────────────────────────────
  2960.   
  2961.   SUNDAY, SUN - Specific day for event to occur
  2962.   MONDAY, MON -    "
  2963.   TUESDAY, TUE -   "
  2964.   WEDNESDAY, WED - "
  2965.   THURSDAY, THU -  "   
  2966.   FRIDAY, FRI -    "   
  2967.   SATURDAY, SAT -  "
  2968.   EVERYDAY - Event occurs everyday
  2969.   TODAY - Event occurs once today only
  2970.   TOMORROW - Event occurs once tomorrow only
  2971.   WEEKDAY, WEEKDAYS - Event occurs only on weekdays
  2972.   WEEKEND, WEEKENDS - Event occurs only on weekends  
  2973.   
  2974.   
  2975. Time tokens
  2976. ─────────────────────────────────────────────────────────────────────
  2977.  
  2978.   {TIME hh:mm (AM)(PM)} - Schedule event time
  2979.   SUNRISE - Calculate time of sunrise
  2980.   SUNSET - Calculate time of sunset
  2981.   {OFFSET +/-hh:mm} - Event occurs +/- 23h59m of prog time
  2982.   NORMAL - Event occurs at specified time
  2983.   SECURITY - Event occurs within the hour
  2984.   {RANDOM +/-hh:mm} - Event occurs within a random offset
  2985.         +/-23h59m.
  2986.   {NOW hh:mm} - Event occurs with respect to current time.
  2987.  
  2988.  
  2989. Specific Date tokens
  2990. ─────────────────────────────────────────────────────────────────────
  2991.  
  2992.   {DATE mm/dd/yyyy} - Event occurs on specified date
  2993.   {DATE mm/dd/yyyy THRU mm/dd/yyyy (SUNDAY...SATURDAY)} - 
  2994.         Event occurs between two dates
  2995.   {EXCEPT mm/dd/yyyy} - Event does NOT occur on specified date
  2996.   {EXCEPT mm/dd/yyyy THRU mm/dd/yyyy (SUNDAY...SATURDAY)} - 
  2997.         Event does NOT occur between two dates
  2998.   {DATE mm/dd/yyyy THRU mm/dd/yyyy EXCEPT mm/dd/yyyy THRU mm/dd/yyyy} -
  2999.         Special exceptions within a given range. 
  3000.  
  3001.  
  3002. Communication tokens
  3003. ─────────────────────────────────────────────────────────────────────
  3004.  
  3005.   {COMx} - send commands via COM1...COM4
  3006.   {IRQ x} - customize IRQ level for port.
  3007.   {IO x}  - customize port address (in hex).
  3008.  
  3009.  
  3010. Miscellaneous tokens
  3011. ─────────────────────────────────────────────────────────────────────
  3012.  
  3013.   {BASECODE x} - Change BASECODE to A...P   
  3014.   {DEFINE x z}      - Substitute string 'x' for 'z'
  3015.   {XACMD file.cmd} - Specify default command file.
  3016.   {INCLUDE filenme} - Specify another file to parse.   
  3017.   {CLEAR EVENT xxx} - Clear event xxx from CP-290 memory
  3018.   ERASE - Erase ALL events from CP-290 memory
  3019.   {EVENT xxx} - Place event xxx in a known location of CP-290 memory
  3020.   BEEP - Causes PC speaker to beep.
  3021.   {DOS command} - Shell to DOS
  3022.   {DISPLAY ON/OFF} - Turn XA output display on or off.
  3023.   DIAGNOSE - CP-290 performs internal diagnostics. 
  3024.  
  3025.  
  3026. Reporting tokens
  3027. ─────────────────────────────────────────────────────────────────────
  3028.  
  3029.   LOG - Append event info to file XA.LOG
  3030.   MONITOR - Watch events as the CP-290 executes them.
  3031.   REPORT1 - Produce report file based on daily events.
  3032.   REPORT2 - Produce report file based on a module by module basis.
  3033.  
  3034.  
  3035. Direct Command Control Tokens
  3036. ─────────────────────────────────────────────────────────────────────
  3037.  
  3038.   :LABEL - Identify an area to "goto/gosub" later.
  3039.   {GOTO label } - Jump to location identified by "label".
  3040.   {GOSUB label} - Execute subroutine identified by "label". Upon
  3041.         returning, continue with the rest of the cmd file.
  3042.   RETURN - from subroutine (used with GOSUB).
  3043.   STOP - Force XA to stop execution
  3044.   :EXIT - Special shutdown location jumped to when <ESC> pressed.
  3045.   {DELAY hh:mm:ss} - Wait for time to pass before executing the
  3046.         next cmd.
  3047.   PAUSE - Halt execution of direct commands until key pressed,
  3048.         then reset internal timer and resume direct commands. 
  3049.   {TIMER hh:mm:ss} - Wait until "seconds" have elapsed (relative
  3050.         to the internal timer).  
  3051.   RESET - Reset internal timer.
  3052.   FAST - ignore ack message from CP-290, speeds up single cmds.
  3053.  
  3054.  
  3055. Conditional Expressions              ( ** Registered Version Only **) 
  3056. ─────────────────────────────────────────────────────────────────────
  3057.  
  3058.   IF (expression)       When expression evaluates TRUE...
  3059.      statements          ...execute the following statements   
  3060.   [ELSE                 Otherwise...
  3061.      statements]         ...optionally execute the following statements   
  3062.   ENDIF                 Must always terminate conditional statements.
  3063.  
  3064.  
  3065. Arithmetic Operators                 ( ** Registered Version Only ** ) 
  3066. ─────────────────────────────────────────────────────────────────────
  3067.  
  3068.   *   Multiply      A = B * C
  3069.   /   Divide      B = A / C
  3070.   +   Addition   C = A + B
  3071.   -   Subtraction   A = C - B
  3072.   -   Unary minus   A = -B
  3073.  
  3074.  
  3075.  
  3076. Relational Operators                 ( ** Registered Version Only ** ) 
  3077. ─────────────────────────────────────────────────────────────────────
  3078.  
  3079.   =   Assign
  3080.   <   Less than
  3081.   >   Greater than
  3082.   <=  Less than or equal to
  3083.   <>  Not equal to
  3084.   >=  Greater than or equal to
  3085.   ==  Equals (not to be confused with '=' assignment operator)
  3086.  
  3087.  
  3088. Logical Operators                   ( ** Registered Version Only ** ) 
  3089. ─────────────────────────────────────────────────────────────────────
  3090.  
  3091.   AND  Logical AND
  3092.   &&   Logical AND
  3093.   OR   Logical OR
  3094.   ||   Logical OR
  3095.   !    NOT
  3096.  
  3097. Bitwise Logical Operators             ( ** Registered Version Only ** ) 
  3098. ─────────────────────────────────────────────────────────────────────
  3099.  
  3100.   &   Bit "AND"
  3101.   |   Bit "OR"
  3102.  
  3103.  
  3104. Screen Color Control                 ( ** Registered Version Only ** ) 
  3105. ─────────────────────────────────────────────────────────────────────
  3106.  
  3107.   {VIDEO1 Foreground Background} - IF or ELSE evaluates to TRUE
  3108.   {VIDEO2 Foreground Background} - IF or ELSE evaluates to FALSE
  3109.   {VIDEO3 Foreground Background} - Sending DIRECT commands to CP-290
  3110.   {VIDEO4 Foreground Background} - Sending EVENTS to CP-290
  3111.  
  3112.   where FOREGROUND may be any of the following:
  3113.      BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
  3114.      DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
  3115.      LIGHTMAGENTA, YELLOW, WHITE
  3116.  
  3117.   and BACKGROUND may be any of the following:
  3118.      BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY
  3119.  
  3120.  
  3121. I/O Port Control                    ( ** Registered Version Only ** ) 
  3122. ─────────────────────────────────────────────────────────────────────
  3123.  
  3124.   {(variable =) INPORT io_port} - read status of port
  3125.   {OUTPORT io_port value} - output value to port
  3126.  
  3127.  
  3128. Pre-defined Variables
  3129. ─────────────────────────────────────────────────────────────────────
  3130.  
  3131.   CDAY - The current day
  3132.   CTIME - The current time
  3133.   CDATE - The current date
  3134.  
  3135.  
  3136. Powerfail Recovery module status overrides 
  3137. ─────────────────────────────────────────────────────────────────────
  3138.  
  3139.   {IGNORE HOUSE UNIT} - Leave module in its present state
  3140.   {FORCE HOUSE-UNIT state} - Force module to ON, OFF, DIM state
  3141.  
  3142.  
  3143. ═════════════════════════════════════════════════════════════════════
  3144. Appendix B. Returned Error Codes 
  3145. ═════════════════════════════════════════════════════════════════════
  3146.  
  3147. The following is a list of Error messages that XA may generate.
  3148. Also included is a specific error code that XA returns when it
  3149. is finished. These error codes may be examined using ERRORLEVEL 
  3150. parameter in batch files.
  3151.  
  3152. Code: 0   "Completed OK."
  3153.            Normal operation, XA ran successfully.
  3154.  
  3155. Code: 1   "No commands to execute."
  3156.            The "-e" command line option was used, preventing any commands
  3157.            or events to be sent to the CP-290. Note that a report file
  3158.            (XA.RPT) may have been generated, however the X10.DAT file was
  3159.            not updated.
  3160.  
  3161. Code: 2   "Timeout occurred. Check your cables."
  3162.            First, make sure the CP-290 is connected to the correct serial
  3163.            port. Also, make sure you are using the proper communication
  3164.            settings.
  3165.  
  3166. Code: 3   "Illegal comm port - Use 1...4."
  3167.            Use i=1...4 only!
  3168.  
  3169. Code: 4   "Timeout occurred or interface defective."
  3170.            XA waited for the CP-290 to return a status code after
  3171.            initiating it's internal diagnostics. First, check to see if the
  3172.            CP-290 is properly connected to the PC. If the connection is OK,
  3173.            then the CP-290 may be defective. All events stored in the
  3174.            CP-290 have been deleted.
  3175.  
  3176. Code: 5   "Interface FAILED diagnostic."
  3177.            The CP-290 has failed its internal diagnostics. All events
  3178.            stored in the CP-290 have been deleted.
  3179.  
  3180. Code: 6   "XA.EXE is corrupt."
  3181.            XA has detected a change in its internal code. This may be the
  3182.            result of a possible virus, or other problem with the file.
  3183.            Re-install XA from the distribution diskette.
  3184.  
  3185. Code: 7   "Timeout occurred. Check cable, irq, and i_o settings."
  3186.            First, make sure the CP-290 is connected to the correct serial
  3187.            port. Also, make sure you are using the proper communication
  3188.            settings.  This type of problem is usually caused by specifying
  3189.            an improper interrupt vector. Run the utility FINDX10.EXE to
  3190.            assist you in determining the proper configuration of your
  3191.            serial port.
  3192.  
  3193. Code: 8    (No error assigned) 
  3194.  
  3195. Code: 9   "Not enough memory."
  3196.            XA reserves memory for "variable" storage, "define" statements,
  3197.            "labels" (for GOTO/GOSUB), and "include" filenames. When this
  3198.            error occurs, try reducing these statements. 
  3199.  
  3200. Code: 10   "<ESC> key pressed. Exiting..."
  3201.            XA was aborted due to operator intervention. A file may not have
  3202.            been downloaded to the CP-290 properly.
  3203.  
  3204. Code: 11   "XA internal date stack overflow."
  3205.            More than 100 dates were specified in a single statement. 
  3206.            Reduce the number of dates, or use DATE ... THRU.
  3207.  
  3208. Code: 12   "XA internal date stack underflow."
  3209.            Try rewriting statement, contact author.
  3210.  
  3211. Code: 13   "XA internal stack overflow."
  3212.            More than 100 tokens were specified in a single statement.
  3213.            Reduce complexity of statement. 
  3214.  
  3215. Code: 14   "XA internal stack underflow."
  3216.            Try rewriting statement, contact author.
  3217.  
  3218. Code: 15   "XA internal gosub stack overflow."
  3219.            Too many levels of subroutines called. Rewrite your command
  3220.            files. 
  3221.  
  3222. Code: 16   "XA internal gosub underflow."
  3223.            Try rewriting statement, contact author.
  3224.  
  3225. Code: 17   "Not enough FILE handles, or file not found."
  3226.            An attempt was made to read or write to a file. The file could
  3227.            not opened because it:               
  3228.               1) does not exist, 
  3229.               2) you need to increase the number of files that can be opened.
  3230.            See DOS manual -          
  3231.               command: FILES=??? (normally in your  CONFIG.SYS).
  3232.  
  3233. Code: 18   "XA internal except date stack overflow."
  3234.            More than 100 "EXCEPT" dates were specified in a single
  3235.            statement. Reduce the number of dates, or use DATE ... THRU.
  3236.  
  3237. Code: 19   "XA internal except date stack underflow."
  3238.            Try rewriting statement, contact author.
  3239.  
  3240. ═════════════════════════════════════════════════════════════════════
  3241. Appendix C. Passing arguments to your command file.
  3242. ═════════════════════════════════════════════════════════════════════
  3243.  
  3244. By default, XA will only accept input from either the DOS
  3245. command line (ie, commands enclosed in "parentheses"), or via a
  3246. file.
  3247.  
  3248.      XA "P1 OFF"   <=== DOS command line arguments.
  3249.      XA F=XA.CMD   <=== XA Command File.
  3250.  
  3251. You may now override this feature and have XA interpret commands
  3252. from the DOS command line as well as a file by using the
  3253. following format:
  3254.  
  3255.      XA "command" f=file.cmd   -or- 
  3256.      XA f=file.cmd "command"   (The order is not important).
  3257.      XA "P1 OFF" f=XA.CMD
  3258.  
  3259. This form of operation is very useful if you wish to pass
  3260. special arguments into your command file and allow XA to
  3261. activate special sequences. Your normal command file (XA.CMD)
  3262. could contain some special commands that are only activated when
  3263. you define a variable to be a certain value. The following
  3264. sample code is included in the SPECIAL.CMD file and is executed
  3265. when the variable "Babysitter" is set TRUE:
  3266.  
  3267.      IF (BABYSITTER)
  3268.         FOYER_LIGHTS ON DUSK TODAY
  3269.         HALLWAY ON SUNSET TODAY
  3270.         DECK_LIGHTS ON SUNSET TODAY
  3271.      ENDIF
  3272.  
  3273. To have XA execute the above sequence, you must program the
  3274. command file name AND the variable assignment statement:
  3275.  
  3276.      XA F=SPECIAL.CMD "BABYSITTER = TRUE"
  3277.  
  3278.  
  3279. ═════════════════════════════════════════════════════════════════════
  3280. Appendix D. Running XA in Windows
  3281. ═════════════════════════════════════════════════════════════════════
  3282.  
  3283. XA may be run in the Windows environment. A major advantage is
  3284. the ability to multi-task your applications while XA monitors
  3285. the CP-290, downloads new event schedules, or performs a special
  3286. lighting sequences.
  3287.  
  3288. In order to use XA successfully in Windows, you must ensure that
  3289. Windows understands your COM port configuration. Follow these
  3290. steps (applies to Windows 3.1):
  3291.  
  3292.  * Run "Program Manger"
  3293.  
  3294.  * In the MAIN group, run "Control Panel"
  3295.  
  3296.  * Run "Ports"
  3297.  
  3298.  * Select the COM port that the CP-290 is connected to. This should
  3299.    match the COM token in you XA.INI file. Press "Settings".
  3300.  
  3301.  * Set the Baud Rate to 600, Data Bits to 8, Parity to None, Stop 
  3302.    Bits to 1, and Flow Control to None.
  3303.  
  3304.  * If you use the tokens "IO, IRQ, i=, o=" in your XA.INI file (or
  3305.    command line), you should press "Advanced..." button to verify
  3306.    these settings.  Make sure the Base I/O Port Address matches the
  3307.    address of your COM port. See the table in the XA documentation
  3308.    for typical addresses of the COM ports.  Next, ensure that the
  3309.    IRQ is set properly. Select "OK".
  3310.  
  3311.  * Select OK.  Windows may need to reboot your machine in order to
  3312.    activate these parameters. 
  3313.  
  3314. Several PIF files were included with XA to perform such
  3315. functions as downloading events, monitoring CP-290 activity, and
  3316. recovering from a power failure. You will need to customize
  3317. these files based on your installation. 
  3318.  
  3319.  
  3320. ═════════════════════════════════════════════════════════════════════
  3321. Appendix E. Updating from Version 1.07b to 2.00 
  3322. ═════════════════════════════════════════════════════════════════════
  3323.  
  3324. There are a few differences with some of the commands in this 
  3325. version. 
  3326.  
  3327.  * GOTO label "x_times"  is no longer supported.  You may either
  3328.    use GOSUBS, or condition statements and counters.
  3329.  
  3330.  * TIMEZONE changes.  Use DST in conjunction with your "Standard
  3331.    Time" timezone. 
  3332.  
  3333.  * DELAY hh:mm:ss  (not DELAY mm:ss)
  3334.  
  3335.  * TIMER mm:ss.hs  Place action tokens before the TIMER tokens:
  3336.      A1 ON TIMER 0:20.5 
  3337.      TIMER 0:20.5 A1 ON     <--- Not this way
  3338.  
  3339.  * DEFINES must be declared prior to their usage in a command.  XA
  3340.    is no longer a multi-pass parser.
  3341.  
  3342.  * X10DAT is no longer supported. The file X10.DAT is always 
  3343.    created.
  3344.  
  3345.  * ADJUST token is no longer supported.
  3346.